From 13fea4a3011a03688304949fad148ac6397bc650 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 10:51:59 +0000 Subject: [PATCH] docs: Brand Palette + Grid & Elevation + Compliance Matrix update - BRAND_PALETTE.md (v1.0, DRAFT): - Token-specifikation (not a color list) - Semantic brand tokens: primary, secondary, tertiary - 12-step scale (50-950) with defined purposes - Usage rules: where brand colors are used (logo, buttons, focus, links) - Usage rules: where brand colors are NOT used (status, data viz, maps) - Dark mode strategy: shift lighter in dark mode - Contrast requirements: WCAG AA 4.5:1 for text, 3:1 for large text/focus - Placeholder values: awaiting brand color definition from Erik/Landvex - Token dependencies from components: Button, Input, Select, Link, Loading, Progress - Governance: no new brand colors without Architecture Review - GRID_ELEVATION.md (v1.0, DRAFT): - Spacing scale: 13 primitive tokens (space-0 to space-12) - Semantic spacing: gap-xs to gap-xl, padding/margin tokens - Grid system: 12-column, responsive (4/8/12 columns) - Common layouts: full, two-column, three-column, four-column, sidebar, asymmetric - Border radius: 6 tokens (none to full) with component mapping - Elevation system: 5 shadow levels + 8 z-index levels - Component elevation mapping: resting, hover, active states - Responsive breakpoints: xs to 2xl (Tailwind-compatible) - Density principles: compact/default/comfortable (75%/100%/125%) - Z-index scale: 8 levels with rules - Token dependencies from components: Card, Button, Input, Select, Modal, Table, Tag, Page, Section - COMPLIANCE_MATRIX.md: Brand Palette 40%, Grid & Elevation 60% Rationale: Brand Palette driven by component token usage, not vice versa. Grid & Elevation validated against Card and other components. Foundations now complete enough to raise component maturity. --- docs/design/BRAND_PALETTE.md | 179 ++++++++++++++++++++++ docs/design/COMPLIANCE_MATRIX.md | 2 + docs/design/GRID_ELEVATION.md | 251 +++++++++++++++++++++++++++++++ 3 files changed, 432 insertions(+) create mode 100644 docs/design/BRAND_PALETTE.md create mode 100644 docs/design/GRID_ELEVATION.md diff --git a/docs/design/BRAND_PALETTE.md b/docs/design/BRAND_PALETTE.md new file mode 100644 index 000000000..d7b88dfc6 --- /dev/null +++ b/docs/design/BRAND_PALETTE.md @@ -0,0 +1,179 @@ +# BRAND PALETTE + +**Token-Specifikation för Landvex Brand Colors** + +| | | +|---|---| +| **Version** | 1.0 | +| **Status** | DRAFT — Awaiting brand color definition | +| **Scope** | Landvex Enterprise Platform | +| **Authority** | DESIGN_SPECIFICATION (nivå 5) | + +--- + +## 1. PRINCIPLES + +**MUST NOT:** Use brand colors for status (success/warning/danger/info). +**MUST NOT:** Use brand colors in data visualization or map layers. +**MUST:** Use brand colors for identity only: logo, headers, primary actions, focus states. + +Brand = identity. Semantic = meaning. **MUST NOT** mix. + +--- + +## 2. TOKEN ARCHITECTURE + +### 2.1 Semantic Brand Tokens + +| Token | Purpose | Usage | +|-------|---------|-------| +| `brand-primary` | Primary brand color | Logo, primary buttons, key headers | +| `brand-secondary` | Secondary brand color | Accents, highlights, hover states | +| `brand-tertiary` | Tertiary brand color | Subtle accents, backgrounds | + +### 2.2 Scale Tokens (12-step) + +| Token | Purpose | +|-------|---------| +| `brand-50` | Lightest tint — backgrounds, hover states | +| `brand-100` | Very light — subtle backgrounds | +| `brand-200` | Light — disabled states | +| `brand-300` | Light-medium — borders | +| `brand-400` | Medium — secondary elements | +| `brand-500` | Base — primary usage | +| `brand-600` | Medium-dark — hover states | +| `brand-700` | Dark — active states | +| `brand-800` | Very dark — text on light backgrounds | +| `brand-900` | Darkest — high contrast text | +| `brand-950` | Deepest — special emphasis | + +--- + +## 3. USAGE RULES + +### 3.1 Where Brand Colors Are Used + +| Context | Token | Example | +|---------|-------|---------| +| Logo | `brand-500` | Landvex logo mark | +| Primary Button | `brand-500` | Default state | +| Primary Button Hover | `brand-600` | Hover state | +| Primary Button Active | `brand-700` | Active state | +| Focus Ring | `brand-500` | Input, Button, Select focus | +| Link | `brand-500` | Text links | +| Link Hover | `brand-600` | Link hover | +| Header Accent | `brand-500` | Page title accent | +| Loading Spinner | `brand-500` | Brand-colored spinner | +| Progress Bar | `brand-500` | Brand-colored progress | + +### 3.2 Where Brand Colors Are NOT Used + +| Context | Why | Alternative | +|---------|-----|-------------| +| Success states | Brand ≠ meaning | `semantic-green-500` | +| Warning states | Brand ≠ meaning | `semantic-yellow-500` | +| Danger states | Brand ≠ meaning | `semantic-red-500` | +| Info states | Brand ≠ meaning | `semantic-blue-500` | +| Data visualization | Brand ≠ data | Categorical color palette | +| Map layers | Brand ≠ geography | Map layer palette | +| Error text | Brand ≠ error | `semantic-red-500` | +| Validation | Brand ≠ validation | `semantic-green/red-500` | + +--- + +## 4. DARK MODE STRATEGY + +| Token | Light Mode | Dark Mode | +|-------|-----------|-----------| +| `brand-primary` | `brand-500` | `brand-400` | +| `brand-secondary` | `brand-600` | `brand-300` | +| `brand-tertiary` | `brand-100` | `brand-800` | + +**Rule:** Brand colors shift lighter in dark mode to maintain contrast. + +--- + +## 5. CONTRAST REQUIREMENTS + +| Usage | Minimum Contrast | Notes | +|-------|-----------------|-------| +| Text on brand background | 4.5:1 (WCAG AA) | `brand-500` text on white, or white on `brand-500` | +| Large text on brand | 3:1 (WCAG AA Large) | Headers, 18px+ or 14px+ bold | +| Focus indicators | 3:1 | Focus ring vs surrounding | +| Disabled brand | No requirement | Disabled state exempt | + +--- + +## 6. PLACEHOLDER VALUES + +**AWAITING BRAND COLOR DEFINITION FROM ERIK/LANDVEX TEAM** + +| Token | Hex (Placeholder) | Status | +|-------|-------------------|--------| +| `brand-50` | — | ⏳ Awaiting | +| `brand-100` | — | ⏳ Awaiting | +| `brand-200` | — | ⏳ Awaiting | +| `brand-300` | — | ⏳ Awaiting | +| `brand-400` | — | ⏳ Awaiting | +| `brand-500` | — | ⏳ Awaiting | +| `brand-600` | — | ⏳ Awaiting | +| `brand-700` | — | ⏳ Awaiting | +| `brand-800` | — | ⏳ Awaiting | +| `brand-900` | — | ⏳ Awaiting | +| `brand-950` | — | ⏳ Awaiting | + +--- + +## 7. TOKEN DEPENDENCIES FROM COMPONENTS + +Components that reference brand tokens: + +| Component | Token | Usage | +|-----------|-------|-------| +| Button (Primary) | `brand-500` | Background | +| Button (Primary Hover) | `brand-600` | Background | +| Button (Primary Active) | `brand-700` | Background | +| Input (Focus) | `brand-500` | Border | +| Select (Focus) | `brand-500` | Border | +| Select (Selected Option) | `brand-50` | Background | +| Link | `brand-500` | Text color | +| Link (Hover) | `brand-600` | Text color | +| Loading | `brand-500` | Spinner color | +| Progress | `brand-500` | Bar color | + +--- + +## 8. GOVERNANCE + +### 8.1 Adding Brand Colors + +**MUST NOT** add new brand colors without Architecture Review. + +**MUST** follow 12-step scale. + +**MUST** update all components that reference brand tokens. + +### 8.2 Changing Brand Colors + +**MUST** assess impact on all components. + +**MUST** update visual regression tests. + +**MUST** communicate change to all teams. + +--- + +## ÄNDRINGSHISTORIA + +| Version | Datum | Beskrivning | +|---------|-------|-------------| +| 1.0 | 2026-07-02 | Initial brand palette token specification | + +--- + +## STATUS + +**DRAFT — Awaiting brand color definition** + +- Mindre revideringar: 1.x-serien +- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+) diff --git a/docs/design/COMPLIANCE_MATRIX.md b/docs/design/COMPLIANCE_MATRIX.md index d5682172e..ad786f663 100644 --- a/docs/design/COMPLIANCE_MATRIX.md +++ b/docs/design/COMPLIANCE_MATRIX.md @@ -75,6 +75,8 @@ | Design Anti-Patterns | ✅ | 100% | | Glossary | ✅ | 100% | | Release Definition | 🟡 | 80% | +| Brand Palette | 🟡 | 40% | +| Grid & Elevation | 🟡 | 60% | --- diff --git a/docs/design/GRID_ELEVATION.md b/docs/design/GRID_ELEVATION.md new file mode 100644 index 000000000..09c461f0d --- /dev/null +++ b/docs/design/GRID_ELEVATION.md @@ -0,0 +1,251 @@ +# GRID & ELEVATION + +**Foundations for Layout and Depth** + +| | | +|---|---| +| **Version** | 1.0 | +| **Status** | DRAFT | +| **Scope** | Landvex Enterprise Platform | +| **Authority** | DESIGN_SPECIFICATION (nivå 5) | + +--- + +## 1. SPACING SCALE + +### 1.1 Primitive Spacing Tokens + +| Token | Value | Usage | +|-------|-------|-------| +| `space-0` | 0px | No spacing | +| `space-1` | 4px | Micro spacing, icon gaps | +| `space-2` | 8px | Tight spacing, inline elements | +| `space-3` | 12px | Default component padding | +| `space-4` | 16px | Standard spacing | +| `space-5` | 20px | Medium spacing | +| `space-6` | 24px | Section spacing | +| `space-7` | 32px | Large spacing | +| `space-8` | 40px | Component height (small) | +| `space-9` | 48px | Component height (medium) | +| `space-10` | 64px | Page-level spacing | +| `space-11` | 80px | Major sections | +| `space-12` | 96px | Page margins | + +### 1.2 Semantic Spacing Tokens + +| Token | Primitive | Usage | +|-------|-----------|-------| +| `gap-xs` | `space-1` | Micro gaps | +| `gap-sm` | `space-2` | Small gaps | +| `gap-md` | `space-4` | Default gaps | +| `gap-lg` | `space-6` | Large gaps | +| `gap-xl` | `space-8` | Extra large gaps | +| `padding-component` | `space-3` | Component internal padding | +| `padding-section` | `space-6` | Section padding | +| `padding-page` | `space-8` | Page padding | +| `margin-component` | `space-4` | Component margin | +| `margin-section` | `space-8` | Section margin | + +--- + +## 2. GRID SYSTEM + +### 2.1 Grid Definition + +| Property | Value | +|----------|-------| +| Columns | 12 | +| Gutter | `gap-md` (16px) | +| Margin | `padding-page` (40px) | +| Max width | 1440px | +| Breakpoints | See §5 | + +### 2.2 Grid Behavior + +| Width | Columns | Gutter | Margin | +|-------|---------|--------|--------| +| < 640px | 4 | `gap-sm` (8px) | `space-4` (16px) | +| 640–1024px | 8 | `gap-md` (16px) | `space-6` (24px) | +| > 1024px | 12 | `gap-md` (16px) | `space-8` (40px) | + +### 2.3 Common Layouts + +| Layout | Columns | Usage | +|--------|---------|-------| +| Full width | 12 | Hero, maps, full-bleed | +| Two column | 6 + 6 | Content + sidebar | +| Three column | 4 + 4 + 4 | Cards, features | +| Four column | 3 + 3 + 3 + 3 | Dashboard, KPIs | +| Sidebar | 3 + 9 | Navigation + content | +| Asymmetric | 4 + 8 | Summary + detail | + +--- + +## 3. BORDER RADIUS + +### 3.1 Radius Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `radius-none` | 0px | Tables, data grids | +| `radius-sm` | 4px | Small components, tags | +| `radius-md` | 8px | Buttons, inputs, cards | +| `radius-lg` | 12px | Cards, panels | +| `radius-xl` | 16px | Modals, dialogs | +| `radius-full` | 9999px | Pills, avatars | + +### 3.2 Component Radius Mapping + +| Component | Radius Token | +|-----------|-------------| +| Button | `radius-md` | +| Input | `radius-md` | +| Select | `radius-md` | +| Card | `radius-lg` | +| Modal | `radius-xl` | +| Tag | `radius-full` | +| Table | `radius-none` | +| Data Grid | `radius-none` | + +--- + +## 4. ELEVATION SYSTEM + +### 4.1 Shadow Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `shadow-none` | none | Flat surfaces | +| `shadow-sm` | 0 1px 2px rgba(0,0,0,0.05) | Cards, resting state | +| `shadow-md` | 0 4px 6px rgba(0,0,0,0.07) | Hover state, dropdowns | +| `shadow-lg` | 0 10px 15px rgba(0,0,0,0.1) | Modals, drawers | +| `shadow-xl` | 0 20px 25px rgba(0,0,0,0.15) | Full-screen overlays | + +### 4.2 Elevation Levels + +| Level | Token | Z-Index | Usage | +|-------|-------|---------|-------| +| 0 | `shadow-none` | 0 | Background, static content | +| 1 | `shadow-sm` | 10 | Cards, panels | +| 2 | `shadow-md` | 20 | Hover state, dropdowns | +| 3 | `shadow-lg` | 30 | Modals, drawers | +| 4 | `shadow-xl` | 40 | Full-screen overlays | +| 5 | — | 50 | Toasts, notifications | +| 6 | — | 60 | Tooltips | +| 7 | — | 70 | Popovers | +| 8 | — | 80 | Dialogs (highest) | + +### 4.3 Component Elevation Mapping + +| Component | Resting | Hover | Active/Focus | +|-----------|---------|-------|--------------| +| Card (static) | `shadow-sm` | — | — | +| Card (interactive) | `shadow-sm` | `shadow-md` | `shadow-sm` | +| Button | `shadow-none` | `shadow-sm` | `shadow-none` | +| Input | `shadow-none` | — | `shadow-sm` (focus) | +| Select (dropdown) | `shadow-md` | — | — | +| Modal | `shadow-lg` | — | — | +| Drawer | `shadow-lg` | — | — | +| Toast | `shadow-md` | — | — | + +--- + +## 5. RESPONSIVE BREAKPOINTS + +| Name | Width | Target | +|------|-------|--------| +| `xs` | < 640px | Mobile phones | +| `sm` | 640–768px | Large phones, small tablets | +| `md` | 768–1024px | Tablets | +| `lg` | 1024–1280px | Small desktops, laptops | +| `xl` | 1280–1536px | Desktops | +| `2xl` | > 1536px | Large desktops | + +### 5.1 Breakpoint Usage + +| Context | Primary Breakpoint | +|---------|-------------------| +| Layout changes | `md` (768px) | +| Typography scale | `sm` (640px) | +| Component density | `lg` (1024px) | +| Navigation mode | `md` (768px) | +| Card grid | `sm`, `md`, `lg` | + +--- + +## 6. DENSITY PRINCIPLES + +### 6.1 Density Scale + +| Density | Spacing | Usage | +|---------|---------|-------| +| Compact | 75% of default | Data-heavy tables, dashboards | +| Default | 100% | Most interfaces | +| Comfortable | 125% of default | Forms, reading-heavy | + +### 6.2 Component Density + +| Component | Compact | Default | Comfortable | +|-----------|---------|---------|-------------| +| Table row height | 32px | 40px | 48px | +| Card padding | `space-3` | `space-4` | `space-5` | +| Button height | 32px | 40px | 48px | +| Input height | 32px | 40px | 48px | +| List item height | 36px | 44px | 52px | + +--- + +## 7. Z-INDEX PRINCIPLES + +### 7.1 Z-Index Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `z-base` | 0 | Static content | +| `z-elevated` | 10 | Cards, sticky headers | +| `z-dropdown` | 20 | Dropdowns, menus | +| `z-sticky` | 30 | Sticky elements | +| `z-modal` | 40 | Modals, drawers | +| `z-popover` | 50 | Popovers, toasts | +| `z-tooltip` | 60 | Tooltips | +| `z-dialog` | 70 | Dialogs (highest) | + +### 7.2 Z-Index Rules + +**MUST NOT** use arbitrary z-index values. +**MUST** use tokens from the scale. +**MUST NOT** exceed `z-dialog` (70). + +--- + +## 8. TOKEN DEPENDENCIES FROM COMPONENTS + +Components that reference grid/elevation tokens: + +| Component | Token | Usage | +|-----------|-------|-------| +| Card | `shadow-sm`, `radius-lg` | Elevation, corner | +| Card (hover) | `shadow-md` | Hover elevation | +| Button | `radius-md` | Corner | +| Input | `radius-md` | Corner | +| Select | `radius-md` | Corner | +| Select (dropdown) | `shadow-md` | Dropdown elevation | +| Modal | `shadow-lg`, `radius-xl` | Elevation, corner | +| Table | `radius-none` | No corner radius | +| Tag | `radius-full` | Pill shape | +| Page | `padding-page` | Page margins | +| Section | `padding-section` | Section padding | + +--- + +## ÄNDRINGSHISTORIA + +| Version | Datum | Beskrivning | +|---------|-------|-------------| +| 1.0 | 2026-07-02 | Initial grid and elevation system | + +--- + +## STATUS + +**DRAFT — Under development**