platform-admin/boc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
16bc14cd327f730dab7a14da319d632ba0ffeb21
boc/docs/design/LANDVEX_DESIGN_SPECIFICATION.md
T
Bernt 16bc14cd32 docs: Token Philosophy v1.1 + Design Specification restructured 
- TOKEN_PHILOSOPHY.md:
  - Added Token Lifecycle (Draft → Experimental → Stable → Deprecated → Removed)
  - Added Design Review Gate (6 mandatory checks before new token)
  - Added deterministic principle: two AI agents must arrive at same token choice
  - Restructured into 8 sections with clear hierarchy

- LANDVEX_DESIGN_SPECIFICATION.md:
  - Restructured into 4 parts: GOVERNANCE → TOKENS → COMPONENTS → VALIDATION
  - Added part headers and updated table of contents
  - Aligned with Token Philosophy lifecycle and review gate

Rationale: Governance before values. Prevents uncontrolled token growth
and ensures AI-assisted design development is deterministic and traceable.
2026-07-02 08:37:50 +00:00

12 KiB
Raw Blame History

LANDVEX DESIGN SPECIFICATION

Technical Contract Between UX, UI, Frontend, AI Agents, QA, and Codebase
Version 1.0-skeleton
Status DRAFT — Under utveckling
Scope Landvex Enterprise Platform
Authority DESIGN_SPECIFICATION (nivå 5 i dokumenthierarkin)
Parent LANDVEX_DESIGN_CONSTITUTION.md

PART A — GOVERNANCE

0. Token Philosophy

See TOKEN_PHILOSOPHY.md for the complete token governance rules.

Quick Reference:

  • Three levels: Primitive → Semantic → Component
  • Semantic first, primitive only when necessary
  • DTCG JSON as canonical format
  • Semantic versioning for token changes
  • Deprecation policy: mark, maintain 2 versions, then remove
  • Token lifecycle: Draft → Experimental → Stable → Deprecated → Removed
  • Design Review Gate required before new token creation

Om detta dokument Detta är ett levande kontrakt. Varje kapitel fylls på successivt. Ingen implementation får bryta mot en specificerad regel. Ospecificerade områden är fria att utforskas, men bör dokumenteras här när de stabiliseras.

Innehållsförteckning

PART A — GOVERNANCE

  1. Token Philosophy

PART B — TOKENS

  1. Design Tokens
    • 1.1 Primitive Tokens
    • 1.2 Semantic Tokens
    • 1.3 Component Tokens
  2. Layout System
  3. Typography
  4. Color System
  5. Motion System
  6. Elevation & Shadows
  7. Iconography

PART C — COMPONENTS

  1. Components
  2. Maps & Geospatial Layer
  3. Accessibility
  4. Responsive Behavior
  5. Empty States
  6. Loading States
  7. Error States

PART D — VALIDATION

  1. Acceptance Criteria
  2. Design QA
  3. Visual Regression
  4. Release Checklist

PART B — TOKENS

1. Design Tokens

Status: ⏳ Ej påbörjad Parent: TOKEN_PHILOSOPHY.md

1.0 Token Architecture

All tokens follow the three-level hierarchy defined in TOKEN_PHILOSOPHY.md:

Level 1: Primitive Tokens  →  Raw values (numbers, colors, dimensions)
Level 2: Semantic Tokens   →  Purpose-driven (surface-primary, text-muted)
Level 3: Component Tokens  →  Component-specific (button-primary-bg-hover)

Rule: Components reference Level 2 (Semantic) by default. Level 3 (Component) only when component-specific override is required. Level 1 (Primitive) never directly from components.

1.1 Primitive Tokens

1.1.1 Spacing Scale

Token Value Usage
space-0 0px —
space-1 4px Tight padding, icon gaps
space-2 8px Default element padding
space-3 12px Component internal spacing
space-4 16px Standard gap
space-5 24px Section spacing
space-6 32px Large section spacing
space-7 48px Page-level spacing
space-8 64px Major section breaks
space-9 96px Hero/page top

1.1.2 Border Radius

Token Value Usage
radius-0 0px Sharp edges (data tables, maps)
radius-1 2px Subtle rounding
radius-2 4px Default (buttons, inputs)
radius-3 8px Cards, panels
radius-4 12px Large cards, modals
radius-full 9999px Pills, avatars

1.1.3 Z-Index Scale

Token Value Usage
z-base 0 Default layer
z-dropdown 100 Dropdowns, popovers
z-sticky 200 Sticky headers
z-modal 300 Modals, dialogs
z-tooltip 400 Tooltips
z-toast 500 Notifications
z-overlay 600 Full-screen overlays

1.1.4 Opacity Scale

Token Value Usage
opacity-0 0% Hidden
opacity-25 25% Disabled text
opacity-50 50% Placeholder text
opacity-75 75% Secondary text
opacity-100 100% Primary content

1.1.5 Blur Scale

Token Value Usage
blur-0 0px No blur
blur-sm 4px Subtle backdrop
blur-md 8px Modal backdrop
blur-lg 16px Full-screen overlay

1.1.6 Border Width

Token Value Usage
border-0 0px No border
border-1 1px Default dividers
border-2 2px Focus rings, active states
border-4 4px Emphasis, errors

1.2 Semantic Tokens

1.2.1 Surface Colors

Token Primitive Reference Usage
surface-primary gray-0 Main background
surface-secondary gray-50 Card background
surface-elevated gray-0 + shadow Modal, popover
surface-overlay gray-900 @ 50% Backdrop

1.2.2 Text Colors

Token Primitive Reference Usage
text-primary gray-900 Headings, body
text-secondary gray-600 Captions, metadata
text-muted gray-400 Placeholders
text-inverse gray-0 On dark surfaces

1.2.3 Border Colors

Token Primitive Reference Usage
border-default gray-200 Dividers
border-focus blue-500 Focus rings
border-error red-500 Error states

1.3 Component Tokens

1.3.1 Button

Token Semantic Reference Usage
button-primary-bg surface-primary Default background
button-primary-bg-hover blue-600 Hover state
button-primary-text text-inverse Label color

1.3.2 Data Grid

Token Semantic Reference Usage
table-row-hover gray-50 Hover highlight
table-header-bg gray-100 Header background

1.4 Export Format

Canonical: DTCG JSON. Derived: CSS custom properties, Tailwind config, Swift, Kotlin.

See TOKEN_PHILOSOPHY.md §3 for full specification.

2. Layout System

Status: ⏳ Ej påbörjad

2.1 Grid

2.2 Breakpoints

Name Width Target
xs 0px Phone portrait
sm 640px Phone landscape
md 768px Tablet portrait
lg 1024px Tablet landscape / small desktop
xl 1280px Desktop
2xl 1536px Large desktop

2.3 Container Widths

2.4 Sidebar / Panel System

3. Typography

Status: ⏳ Ej påbörjad

3.1 Font Stack

3.2 Type Scale

Token Size Line Height Weight Letter Spacing Usage
text-xs 12px 16px 400 0.01em Captions, metadata
text-sm 14px 20px 400 0 Body small
text-base 16px 24px 400 0 Body
text-lg 18px 28px 400 -0.01em Lead paragraph
text-xl 20px 28px 500 -0.02em Section headers
text-2xl 24px 32px 500 -0.02em Page titles
text-3xl 30px 36px 600 -0.02em Major headings
text-4xl 36px 40px 600 -0.03em Hero titles

3.3 Font Weights

3.4 Monospace (Data)

4. Color System

Status: ⏳ Ej påbörjad

4.1 Neutral Scale

4.2 Primary Colors

4.3 Semantic Colors

4.4 Data Visualization Colors

4.5 Map Colors

5. Motion System

Status: ⏳ Ej påbörjad

5.1 Duration Scale

Token Value Usage
duration-instant 0ms No animation
duration-fast 100ms Hover states
duration-normal 200ms Standard transitions
duration-slow 300ms Page transitions
duration-slower 500ms Complex animations

5.2 Easing Functions

Token Value Usage
ease-linear linear Continuous motion
ease-in cubic-bezier(0.4, 0, 1, 1) Exit animations
ease-out cubic-bezier(0, 0, 0.2, 1) Enter animations
ease-in-out cubic-bezier(0.4, 0, 0.2, 1) Standard
ease-spring cubic-bezier(0.34, 1.56, 0.64, 1) Playful interactions

5.3 Motion Principles

6. Elevation & Shadows

Status: ⏳ Ej påbörjad

6.1 Shadow Scale

6.2 Usage Rules

7. Iconography

Status: ⏳ Ej påbörjad

7.1 Icon Set

7.2 Icon Sizes

7.3 Icon + Text Pairing

PART C — COMPONENTS

8. Components

Status: ⏳ Ej påbörjad

Princip: Varje komponent har en egen specifikation med states, ARIA, keyboard, touch, animation och acceptance criteria.

8.1 Button

States:

  • Default
  • Hover
  • Focus
  • Pressed (Active)
  • Loading
  • Disabled

Variants:

  • Primary
  • Secondary
  • Tertiary (Ghost)
  • Danger
  • Icon-only

ARIA:

  • role="button"
  • aria-label for icon-only
  • aria-disabled for disabled
  • aria-busy for loading

Keyboard:

  • Enter / Space to activate
  • Tab to focus

Touch:

  • Min 44x44px touch target
  • Active state on press

Animation:

  • Hover: background-color 100ms ease-out
  • Press: scale(0.98) 50ms
  • Loading: spinner rotation 1s linear infinite

Acceptance Criteria:

  • All states are visually distinct
  • Focus ring is visible
  • Loading state prevents double-submit
  • Disabled state is not focusable
  • Touch target meets 44px minimum

8.2 Input / Text Field

8.3 Select / Dropdown

8.4 Checkbox

8.5 Radio Button

8.6 Toggle / Switch

8.7 Card

8.8 Modal / Dialog

8.9 Toast / Notification

8.10 Tooltip

8.11 Data Table

8.12 Tabs

8.13 Navigation

8.14 Sidebar

8.15 Map Overlay

9. Maps & Geospatial Layer

Status: ⏳ Ej påbörjad

9.1 Mapbox Configuration

9.2 Layer Styles

9.3 Interaction Patterns

9.4 Geometries & Coordinates Display

10. Accessibility

Status: ⏳ Ej påbörjad

10.1 WCAG 2.1 AA Compliance

10.2 Keyboard Navigation

10.3 Screen Reader Support

10.4 Focus Management

10.5 Color Contrast

10.6 Reduced Motion

11. Responsive Behavior

Status: ⏳ Ej påbörjad

11.1 Device Adaptive Principles

11.2 Phone (< 768px)

11.3 Tablet (768px - 1024px)

11.4 Desktop (> 1024px)

12. Empty States

Status: ⏳ Ej påbörjad

12.1 Principles

12.2 Patterns by Context

13. Loading States

Status: ⏳ Ej påbörjad

13.1 Skeleton Patterns

13.2 Progress Indicators

13.3 Stepped Loading

14. Error States

Status: ⏳ Ej påbörjad

14.1 Error Message Structure

14.2 Inline Errors

14.3 Page-Level Errors

14.4 Toast Errors

PART D — VALIDATION

15. Acceptance Criteria

Status: ⏳ Ej påbörjad

15.1 Definition of Done (Design)

15.2 Checklist per Component

15.3 Cross-Browser Requirements

16. Design QA

Status: ⏳ Ej påbörjad

16.1 Manual Review Process

16.2 Automated Checks (Future)

16.3 Screenshot Review

17. Visual Regression

Status: ⏳ Ej påbörjad — Fas 3

17.1 Scope

17.2 Tools

17.3 Thresholds

18. Release Checklist

Status: ⏳ Ej påbörjad

18.1 Pre-Release Design Review

18.2 Post-Release Verification

ÄNDRINGSHISTORIA

Version Datum Beskrivning
1.0-skeleton 2026-07-02 Initial struktur med 18 kapitel, tomt innehåll

STATUS

DRAFT — Under utveckling

  • Fyll på kapitel successivt
  • Markera kapitel som ✅ när de är specificerade och godkända
  • Brytande ändringar: Kräver Architecture Review
Reference in New Issue View Git Blame Copy Permalink