init
This commit is contained in:
Matt Batchelder
391
DESIGN_SYSTEM.md
Normal file
391
DESIGN_SYSTEM.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# Design System Reference Card
|
||||
|
||||
A quick visual and technical reference for the OTS Signage Modern Theme.
|
||||
|
||||
## 🎨 Color Palette
|
||||
|
||||
### Brand Colors
|
||||
```
|
||||
--color-primary #2563eb ████████████ Blue
|
||||
--color-primary-dark #1d4ed8 ██████████ Darker Blue
|
||||
--color-primary-light #3b82f6 ██████████████ Lighter Blue
|
||||
--color-secondary #7c3aed ████████████ Purple
|
||||
```
|
||||
|
||||
### Status Colors
|
||||
```
|
||||
--color-success #10b981 ██████████ Green
|
||||
--color-warning #f59e0b ██████████ Amber
|
||||
--color-danger #ef4444 ██████████ Red
|
||||
--color-info #0ea5e9 ██████████ Cyan
|
||||
```
|
||||
|
||||
### Gray Scale (Neutral)
|
||||
```
|
||||
Level Color Hex Usage
|
||||
50 Very Light #f9fafb Backgrounds, light surfaces
|
||||
100 Light #f3f4f6 Hover states, borders
|
||||
200 Light Gray #e5e7eb Borders, dividers
|
||||
300 Gray #d1d5db Form inputs, disabled
|
||||
400 Gray #9ca3af Placeholder text
|
||||
500 Medium Gray #6b7280 Secondary text
|
||||
600 Dark Gray #4b5563 Body text, labels
|
||||
700 Darker Gray #374151 Headings
|
||||
800 Very Dark #1f2937 Primary text
|
||||
900 Darkest #111827 High contrast text
|
||||
```
|
||||
|
||||
### Semantic Colors
|
||||
```
|
||||
--color-background #ffffff (dark: #0f172a)
|
||||
--color-surface #f9fafb (dark: #1e293b)
|
||||
--color-surface-elevated #ffffff (dark: #334155)
|
||||
--color-text-primary #1f2937 (dark: #f1f5f9)
|
||||
--color-text-secondary #6b7280 (dark: #cbd5e1)
|
||||
--color-text-tertiary #9ca3af (dark: #94a3b8)
|
||||
--color-border #e5e7eb (dark: #475569)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Typography Scale
|
||||
|
||||
### Font Family
|
||||
```
|
||||
--font-family-base: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
|
||||
--font-family-mono: "SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Menlo, Courier, monospace
|
||||
```
|
||||
|
||||
### Font Sizes
|
||||
```
|
||||
Size Pixels Usage
|
||||
--font-size-xs 12px Small labels, badges, captions
|
||||
--font-size-sm 14px Form hints, table cells, small text
|
||||
--font-size-base 16px Body text, default size
|
||||
--font-size-lg 18px Subheadings, callouts
|
||||
--font-size-xl 20px Section headings
|
||||
--font-size-2xl 24px Page headings
|
||||
--font-size-3xl 30px Large headings
|
||||
--font-size-4xl 36px Main titles
|
||||
```
|
||||
|
||||
### Font Weights
|
||||
```
|
||||
Weight Value Usage
|
||||
--font-weight-normal 400 Body text, regular content
|
||||
--font-weight-medium 500 Form labels, emphasis
|
||||
--font-weight-semibold 600 Headings, strong emphasis
|
||||
--font-weight-bold 700 Major headings, highlights
|
||||
```
|
||||
|
||||
### Line Heights
|
||||
```
|
||||
Height Value Usage
|
||||
--line-height-tight 1.25 Tight headings
|
||||
--line-height-snug 1.375 Subheadings
|
||||
--line-height-normal 1.5 Default, body text
|
||||
--line-height-relaxed 1.625 Large text blocks
|
||||
--line-height-loose 2 Extra spacing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📏 Spacing Scale (8px base unit)
|
||||
|
||||
```
|
||||
Token Pixels CSS Rem
|
||||
--space-1 4px 0.25rem Tightest spacing
|
||||
--space-2 8px 0.5rem Small padding
|
||||
--space-3 12px 0.75rem Medium-small
|
||||
--space-4 16px 1rem Standard padding
|
||||
--space-5 20px 1.25rem Medium spacing
|
||||
--space-6 24px 1.5rem Default margins
|
||||
--space-7 28px 1.75rem Large spacing
|
||||
--space-8 32px 2rem Section spacing
|
||||
--space-10 40px 2.5rem Large spacing
|
||||
--space-12 48px 3rem Very large
|
||||
--space-16 64px 4rem Extra large
|
||||
--space-20 80px 5rem Massive spacing
|
||||
```
|
||||
|
||||
**Usage Example:**
|
||||
```css
|
||||
.widget {
|
||||
padding: var(--space-6); /* 24px all sides */
|
||||
margin-bottom: var(--space-8); /* 32px below */
|
||||
gap: var(--space-4); /* 16px between items */
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎭 Shadows (Elevation System)
|
||||
|
||||
```
|
||||
Level Shadow Usage
|
||||
none none No elevation
|
||||
xs 0 1px 2px 0 rgba(0, 0, 0, 0.05) Subtle depth
|
||||
sm 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 ... Small cards
|
||||
base 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px ... Default cards
|
||||
md 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px ... Medium elevation
|
||||
lg 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px ... Large hover
|
||||
xl 0 25px 50px -12px rgba(0, 0, 0, 0.25) Maximum depth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔲 Border Radius
|
||||
|
||||
```
|
||||
Token Pixels Usage
|
||||
--radius-none 0px Sharp corners
|
||||
--radius-sm 4px Minimal rounding
|
||||
--radius-base 6px Default input fields
|
||||
--radius-md 8px Standard components
|
||||
--radius-lg 12px Cards, modals
|
||||
--radius-xl 16px Large containers
|
||||
--radius-2xl 24px Extra rounded
|
||||
--radius-full 9999px Fully rounded (pills, circles)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Transitions
|
||||
|
||||
```
|
||||
Token Duration Easing Usage
|
||||
--transition-fast 150ms ease-in-out Hover, quick interactions
|
||||
--transition-base 200ms ease-in-out Default, UI changes
|
||||
--transition-slow 300ms ease-in-out Page transitions, major changes
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```css
|
||||
a {
|
||||
transition: color var(--transition-fast);
|
||||
}
|
||||
|
||||
.widget {
|
||||
transition: box-shadow var(--transition-base), transform var(--transition-base);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📱 Responsive Breakpoints
|
||||
|
||||
```
|
||||
Name Width Use Case
|
||||
sm 640px Mobile phones (landscape)
|
||||
md 768px Tablets
|
||||
lg 1024px Desktop screens
|
||||
xl 1280px Large desktops
|
||||
2xl 1536px Ultra-wide displays
|
||||
```
|
||||
|
||||
**Usage Pattern (Mobile-First):**
|
||||
```css
|
||||
/* Mobile first (default) */
|
||||
.widget {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
/* Tablets and up */
|
||||
@media (min-width: 768px) {
|
||||
.widget {
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
}
|
||||
}
|
||||
|
||||
/* Desktops and up */
|
||||
@media (min-width: 1024px) {
|
||||
.widget {
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Component Reference
|
||||
|
||||
### Buttons
|
||||
```css
|
||||
.btn {
|
||||
padding: var(--space-3) var(--space-4); /* 12px × 16px */
|
||||
border-radius: var(--radius-md); /* 8px */
|
||||
font-weight: var(--font-weight-medium); /* 500 */
|
||||
font-size: var(--font-size-base); /* 16px */
|
||||
}
|
||||
|
||||
.btn-primary {
|
||||
background: var(--color-primary); /* #2563eb */
|
||||
color: var(--color-text-inverse); /* White */
|
||||
}
|
||||
|
||||
.btn-primary:hover {
|
||||
background: var(--color-primary-dark); /* #1d4ed8 */
|
||||
}
|
||||
```
|
||||
|
||||
### Form Inputs
|
||||
```css
|
||||
input, textarea, select {
|
||||
background: var(--color-background); /* #ffffff */
|
||||
border: 1px solid var(--color-border); /* #e5e7eb */
|
||||
border-radius: var(--radius-md); /* 8px */
|
||||
padding: var(--space-3) var(--space-4); /* 12px × 16px */
|
||||
font-size: var(--font-size-base); /* 16px */
|
||||
}
|
||||
|
||||
input:focus {
|
||||
border-color: var(--color-primary); /* #2563eb */
|
||||
box-shadow: 0 0 0 3px var(--color-primary-lighter);
|
||||
}
|
||||
```
|
||||
|
||||
### Cards/Widgets
|
||||
```css
|
||||
.widget {
|
||||
background: var(--color-surface-elevated); /* #ffffff */
|
||||
border: 1px solid var(--color-border); /* #e5e7eb */
|
||||
border-radius: var(--radius-lg); /* 12px */
|
||||
box-shadow: var(--shadow-sm); /* Subtle depth */
|
||||
padding: var(--space-6); /* 24px */
|
||||
}
|
||||
|
||||
.widget:hover {
|
||||
box-shadow: var(--shadow-base); /* More elevation */
|
||||
transform: translateY(-1px); /* Slight lift */
|
||||
}
|
||||
```
|
||||
|
||||
### Alerts
|
||||
```css
|
||||
.alert {
|
||||
border-radius: var(--radius-md); /* 8px */
|
||||
padding: var(--space-4) var(--space-6); /* 16px × 24px */
|
||||
border-left: 4px solid var(--color-success);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌙 Dark Mode
|
||||
|
||||
All colors automatically switch when `prefers-color-scheme: dark` is detected:
|
||||
|
||||
```css
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root {
|
||||
--color-background: #0f172a; /* Deep navy */
|
||||
--color-surface: #1e293b; /* Slate */
|
||||
--color-text-primary: #f1f5f9; /* Near white */
|
||||
/* ... other dark mode overrides ... */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Test in Browser DevTools:**
|
||||
1. F12 (Open DevTools)
|
||||
2. Ctrl+Shift+P (Search in Chrome)
|
||||
3. Type "rendering"
|
||||
4. Toggle "Prefers color scheme" to dark
|
||||
5. Page updates instantly
|
||||
|
||||
---
|
||||
|
||||
## ♿ Accessibility
|
||||
|
||||
### Color Contrast
|
||||
```
|
||||
Element Ratio WCAG Level
|
||||
Primary text on white 7:1 AAA
|
||||
Secondary text on white 4.5:1 AA
|
||||
Links on white 5:1 AA
|
||||
Buttons 4.5:1 AA
|
||||
```
|
||||
|
||||
### Focus Indicators
|
||||
```css
|
||||
*:focus-visible {
|
||||
outline: 2px solid var(--color-primary); /* #2563eb */
|
||||
outline-offset: 2px;
|
||||
}
|
||||
```
|
||||
|
||||
### Keyboard Navigation
|
||||
- All interactive elements are tab-accessible
|
||||
- Logical tab order maintained
|
||||
- No keyboard traps
|
||||
- Focus always visible
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Using CSS Variables
|
||||
|
||||
### Override in Your Code
|
||||
```css
|
||||
/* In your custom CSS, you can override tokens: */
|
||||
:root {
|
||||
--color-primary: #006bb3; /* Your brand blue */
|
||||
--font-size-base: 18px; /* Larger default text */
|
||||
}
|
||||
|
||||
/* All components using tokens will update automatically */
|
||||
```
|
||||
|
||||
### Reference in Components
|
||||
```css
|
||||
.my-component {
|
||||
background: var(--color-surface);
|
||||
color: var(--color-text-primary);
|
||||
padding: var(--space-4);
|
||||
border-radius: var(--radius-md);
|
||||
box-shadow: var(--shadow-base);
|
||||
}
|
||||
```
|
||||
|
||||
### With Fallbacks (IE11 compat, optional)
|
||||
```css
|
||||
.my-component {
|
||||
background: #f9fafb; /* Fallback */
|
||||
background: var(--color-surface); /* Modern */
|
||||
|
||||
color: #1f2937; /* Fallback */
|
||||
color: var(--color-text-primary); /* Modern */
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Quick Lookup Table
|
||||
|
||||
| Need | Variable | Value |
|
||||
|------|----------|-------|
|
||||
| Brand color | `--color-primary` | #2563eb |
|
||||
| Button padding | `--space-3` + `--space-4` | 12px × 16px |
|
||||
| Card shadow | `--shadow-base` | 4px 6px -1px rgba... |
|
||||
| Body text | `--font-size-base` | 16px |
|
||||
| Heading | `--font-size-2xl` | 24px |
|
||||
| Default spacing | `--space-6` | 24px |
|
||||
| Card radius | `--radius-lg` | 12px |
|
||||
| Focus outline | `--color-primary` | #2563eb |
|
||||
| Dark background | --color-surface (dark mode) | #1e293b |
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Pro Tips
|
||||
|
||||
1. **Always use variables** — Don't hardcode colors or sizes
|
||||
2. **Spacing is 8px-based** — Use `--space-*` for consistency
|
||||
3. **Test dark mode** — Use DevTools (see above)
|
||||
4. **Mobile-first queries** — Styles default to mobile, expand on larger screens
|
||||
5. **Focus states matter** — Never remove `outline` without adding alternative
|
||||
6. **Semantic colors** — Use `--color-surface` instead of hardcoding #ffffff
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: February 2026
|
||||
**Theme Version**: 1.0.0 (Modern)
|
||||
**Xibo Compatibility**: 3.x+
|
||||
Reference in New Issue
Block a user