@schneiderjoseph/devia 0.1.0

package/standard/design/decisions/ADR-002-radius-scale.md

@@ -0,0 +1,9 @@
+# ADR-002: Radius scale
+
+## Decision
+
+Finite radius tokens (e.g. none/sm/md/lg/full). No per-component random radii.
+
+## Status
+
+Accepted

package/standard/design/decisions/ADR-003-color-system.md

@@ -0,0 +1,9 @@
+# ADR-003: Color system
+
+## Decision
+
+Primitive palette → semantic aliases (text, surface, border, status, brand). Themes swap semantics.
+
+## Status
+
+Accepted

package/standard/design/decisions/ADR-004-component-versioning.md

@@ -0,0 +1,9 @@
+# ADR-004: Component versioning
+
+## Decision
+
+Version the component package with semver; breaking a11y/visual API → major.
+
+## Status
+
+Accepted

package/standard/design/decisions/README.md

@@ -0,0 +1,3 @@
+# Architecture decision records (design system)
+
+Use ADRs for irreversible token/component choices.

package/standard/design/design-system/components.md

@@ -0,0 +1,9 @@
+# Design-system components
+
+A component is ready when:
+
+1. Tokens wired
+2. States documented
+3. A11y behavior documented (APG link if composite)
+4. Code + Penpot (or explicit ‘code-only’) stay aligned
+5. Usage do/don’t in docs

package/standard/design/design-system/naming.md

@@ -0,0 +1,19 @@
+# Naming
+
+```text
+{category}.{role}.{variant}.{state?}
+```
+
+Examples:
+
+```text
+color.text.primary
+color.background.surface
+space.4
+radius.md
+button.primary.background
+button.primary.background.hover
+```
+
+- Prefer English kebab/dot tokens stable across products
+- Product branding overrides semantic tokens in a product layer — do not fork core component code per product when tokens suffice

package/standard/design/design-system/tokens.md

@@ -0,0 +1,7 @@
+# Tokens
+
+Canonical rules:
+
+- [DS-001](../../../rules/design-system/DS-001.md)
+- [DS-002](../../../rules/design-system/DS-002.md)
+- [DS-003](../../../rules/design-system/DS-003.md)

package/standard/design/design-system/variants.md

@@ -0,0 +1,5 @@
+# Variants
+
+- Variants are finite and documented (size, tone, emphasis)
+- Do not explode combinatorial variants that are unused
+- Each variant lists required states

package/standard/design/design-system/versioning.md

@@ -0,0 +1,5 @@
+# Versioning the design system
+
+- Semantic versioning for token/component packages
+- Breaking visual changes → major + migration notes
+- Changelog required for shipped token renames

package/standard/design/health/coverage.md

@@ -0,0 +1 @@
+Track which screens/components claim conformance to which rule IDs.

package/standard/design/health/dashboard.md

@@ -0,0 +1,14 @@
+# Example dashboard output
+
+```text
+DESIGN SYSTEM HEALTH
+
+Accessibility       —
+Token coverage      —
+Component reuse     —
+Responsive          —
+UX compliance       —
+Documentation       —
+
+Overall              —  (fill from app metrics)
+```

package/standard/design/health/maturity-model.md

@@ -0,0 +1,9 @@
+# Design-system maturity
+
+| Level | Meaning |
+|---|---|
+| 0 | Ad-hoc UI |
+| 1 | Tokens exist |
+| 2 | Core components + a11y MUST pass |
+| 3 | Patterns + states + CI rule validation |
+| 4 | Measured health + AI review gates |

package/standard/design/health/score.md

@@ -0,0 +1,14 @@
+# Scoring model (informative)
+
+```text
+Accessibility       % of MUST a11y rules passing
+Token coverage      UI surfaces using semantic tokens
+Component reuse     Screens using system components
+Responsive          RWD MUST pass
+UX compliance       UX MUST pass
+Documentation       Components documented
+
+Overall = weighted average (product-defined weights)
+```
+
+Compute in the **application** repo; this standard defines the rubric.

package/standard/design/interaction/README.md

@@ -0,0 +1,10 @@
+# Input methods
+
+| Method | Doc |
+|---|---|
+| Mouse | [`mouse.md`](mouse.md) |
+| Keyboard | [`keyboard.md`](keyboard.md) |
+| Touch | [`touch.md`](touch.md) |
+| Touchscreen (fixed) | [`touchscreen.md`](touchscreen.md) |
+| Pen | [`pen.md`](pen.md) |
+| Voice | [`voice.md`](voice.md) |

package/standard/design/interaction/keyboard.md

@@ -0,0 +1,3 @@
+- Full operability (A11Y-004)
+- Visible focus (A11Y-006)
+- APG patterns for composites (A11Y-002)

package/standard/design/interaction/mouse.md

@@ -0,0 +1,2 @@
+- Hover may enhance, never be the only affordance (RWD-003)
+- Precise targets may be smaller than touch, still ≥ A11Y-010

package/standard/design/interaction/pen.md

@@ -0,0 +1 @@
+- Pen precision allows denser UI than finger; still provide finger-safe primary actions when shared devices

package/standard/design/interaction/touch.md

@@ -0,0 +1,3 @@
+- Prefer 44×44 primary actions (INT-001)
+- Spacing between targets to reduce mis-taps
+- No hover-only reveal

package/standard/design/interaction/touchscreen.md

@@ -0,0 +1,6 @@
+# Fixed touchscreen / kiosk-like
+
+- Large primary actions; gloves/lighting may reduce precision
+- Avoid multi-step hover menus
+- Confirm destructive actions (UX-011)
+- High contrast under bright ambient light (A11Y-008)

package/standard/design/interaction/voice.md

@@ -0,0 +1,2 @@
+- Voice is progressive enhancement; never the only path to critical tasks unless product explicitly requires it
+- Spoken names must match accessible names

package/standard/design/localization/README.md

@@ -0,0 +1,5 @@
+# Localization
+
+Rules: I18N-001… in `rules/localization/`.
+
+Supports multi-locale products (e.g. FR/EN) and multi-currency display without hardcoding one market’s formats.

package/standard/design/localization/currency.md

@@ -0,0 +1,3 @@
+# currency
+
+See DATA-001.

package/standard/design/localization/date-time.md

@@ -0,0 +1,3 @@
+# date-time
+
+Locale formatters; see DATA-002.

package/standard/design/localization/i18n.md

@@ -0,0 +1,3 @@
+# i18n
+
+Externalize strings; no UI copy only in code comments.

package/standard/design/localization/locale-testing.md

@@ -0,0 +1,3 @@
+# locale-testing
+
+Test with long pseudo-locale / real secondary locale before release.

package/standard/design/localization/number-formatting.md

@@ -0,0 +1,3 @@
+# number-formatting
+
+Use Intl / locale libraries.

package/standard/design/localization/pluralization.md

@@ -0,0 +1,3 @@
+# pluralization
+
+Use proper plural rules per locale — not English-only ternary.

package/standard/design/localization/rtl.md

@@ -0,0 +1,3 @@
+# rtl
+
+I18N-003 when RTL in scope.

package/standard/design/localization/text-expansion.md

@@ -0,0 +1,3 @@
+# text-expansion
+
+I18N-002.

package/standard/design/motion/animation.md

@@ -0,0 +1,6 @@
+# Animation
+
+Canonical rules:
+
+- [A11Y-012](../../../rules/accessibility/A11Y-012.md)
+- [MOT-001](../../../rules/motion/MOT-001.md)

package/standard/design/penpot/WORKFLOW.md

@@ -0,0 +1,27 @@
+# Penpot workflow
+
+[Penpot](https://github.com/penpot/penpot) is recommended as the **visual** design-system surface (components, libraries, inspect). Self-host optional.
+
+## Source of truth split
+
+```text
+GitHub
+├── tokens/           ← SSOT for values
+├── rules (this repo) ← SSOT for policy
+└── component code    ← SSOT for behavior
+
+Penpot
+└── visual library    ← SSOT for layout/comps visuals (synced)
+```
+
+## Practice
+
+1. Define/change tokens in Git first (or export immediately to Git)
+2. Update Penpot shared library components
+3. Publish library; products consume
+4. Handoff via inspect + token names — not screenshots alone
+5. AI agents read **this repo + tokens**, not only PNG exports
+
+## MCP / API
+
+Prefer structured tokens + this standard over “recreate from screenshot” prompts.

package/standard/design/platforms/README.md

@@ -0,0 +1,12 @@
+# Platforms
+
+Rules apply differently by surface. Default assumption is **web**. Override with platform notes when shipping native or touch-first UIs.
+
+| Surface | Notes |
+|---|---|
+| [`web/`](web/) | Baseline for this standard |
+| [`mobile/`](mobile/) | iOS/Android app shells |
+| [`tablet/`](tablet/) | Larger touch productivity |
+| [`desktop/`](desktop/) | Dense admin / keyboard-heavy |
+
+See also [`interaction/`](../interaction/) for input methods.

package/standard/design/platforms/desktop/README.md

@@ -0,0 +1,5 @@
+# Desktop
+
+- Keyboard efficiency matters (A11Y-004)
+- Higher information density allowed if contrast/targets still pass
+- Hover enhancements OK if keyboard equivalent exists (RWD-003)

package/standard/design/platforms/mobile/android.md

@@ -0,0 +1,5 @@
+# Android
+
+- Prefer Material navigation patterns when native
+- TalkBack names required (A11Y-001)
+- Touch targets per Material / A11Y-010

package/standard/design/platforms/mobile/ios.md

@@ -0,0 +1,5 @@
+# iOS
+
+- Prefer platform HIG for navigation chrome; still meet this standard’s a11y intent
+- Touch targets: follow Apple HIG sizing; never below A11Y-010
+- VoiceOver labels required for icon-only controls (A11Y-001)

package/standard/design/platforms/tablet/README.md

@@ -0,0 +1,5 @@
+# Tablet
+
+- Hybrid: touch-first density with optional keyboard
+- Avoid hover-only actions (RWD-003, INT-001)
+- Tables: prefer card/list alternatives or horizontal scroll with sticky headers + accessible alternative

package/standard/design/platforms/web/README.md

@@ -0,0 +1 @@
+Web is the default platform. Apply full WCAG-oriented MUST set unless waived.

package/standard/design/principles/design-principles.md

@@ -0,0 +1,9 @@
+# Design principles
+
+1. **Clarity** — one primary job per view
+2. **Consistency** — same problem → same pattern
+3. **Feedback** — every action shows system status
+4. **Forgiveness** — prevent errors; make recovery obvious
+5. **Efficiency** — shorten frequent paths; don’t punish experts for novice defaults
+6. **Inclusion** — accessible by default, not as polish
+7. **Restraint** — remove until it breaks; then put back one thing

package/standard/design/principles/ui-principles.md

@@ -0,0 +1,7 @@
+# UI principles
+
+- Hierarchy: brand/product identity → primary action → supporting content
+- Spacing and type scales come from **tokens**, not ad-hoc pixels
+- One composition per viewport job (avoid dashboard clutter on simple tasks)
+- Prefer full-bleed structure only when the product surface calls for it; otherwise respect content width
+- Motion communicates state changes; it is not decoration by default

package/standard/design/principles/ux-principles.md

@@ -0,0 +1,14 @@
+# UX principles
+
+Aligned with NN/g heuristics (interpretive, not a reprint).
+
+1. Visibility of system status
+2. Match the real world / domain language of users
+3. User control and freedom (undo, cancel, escape)
+4. Consistency and standards
+5. Error prevention
+6. Recognition rather than recall
+7. Flexibility and efficiency of use
+8. Aesthetic and minimalist design (no irrelevant chrome)
+9. Help users recognize, diagnose, and recover from errors
+10. Help and documentation when the UI cannot be self-evident

package/standard/design/references/atlassian.md

@@ -0,0 +1,3 @@
+# ATLASSIAN
+
+Atlassian Design System: product/app shells, denser SaaS patterns.

package/standard/design/references/carbon.md

@@ -0,0 +1,3 @@
+# CARBON
+
+IBM Carbon: tokens, themes, data-dense product UI structure.

package/standard/design/references/figma-sds.md

@@ -0,0 +1,5 @@
+# Figma SDS
+
+Simple Design System — reference architecture for variables/components ↔ code. Learn patterns; Penpot remains our visual tool.
+
+https://github.com/figma/sds

package/standard/design/references/govuk.md

@@ -0,0 +1,3 @@
+# GOVUK
+
+GOV.UK Design System: styles, components, patterns, content design. Excellent for forms/errors/services.

package/standard/design/references/material.md

@@ -0,0 +1,3 @@
+# MATERIAL
+
+Material Design 3: mobile/responsive/motion patterns — adapt, don’t clone branding.

package/standard/design/references/nng.md

@@ -0,0 +1,3 @@
+# NNG
+
+Nielsen Norman Group: usability heuristics and research. Level 2 — guidelines, not law.

package/standard/design/references/openui.md

@@ -0,0 +1,3 @@
+# OPENUI
+
+OpenUI: evolving web component/primitives standards — watch for native control convergence.

package/standard/design/references/primer.md

@@ -0,0 +1,5 @@
+# Primer
+
+GitHub Primer — design guidelines, components, tooling. Useful reference for product/UI engineering alignment.
+
+https://primer.style/

package/standard/design/references/storybook.md

@@ -0,0 +1,3 @@
+# Storybook
+
+Workshop for building, documenting, and testing UI components in isolation — complements this standard’s component readiness bar.

package/standard/design/references/uswds.md

@@ -0,0 +1,3 @@
+# USWDS
+
+U.S. Web Design System: government-scale patterns and components.

package/standard/design/references/w3c.md

@@ -0,0 +1,3 @@
+# W3C
+
+WCAG 2.2 + WAI-ARIA + APG are Level 1 normative sources. Prefer primary W3C text for audits.

package/standard/design/responsive/desktop.md

@@ -0,0 +1,4 @@
+# Desktop
+
+- Prefer density suited to productivity UIs when the product is tool-like
+- Hover affordances MUST have keyboard/touch equivalents

package/standard/design/responsive/mobile.md

@@ -0,0 +1,6 @@
+# Mobile
+
+Canonical rules:
+
+- [RWD-001](../../../rules/responsive/RWD-001.md)
+- [RWD-002](../../../rules/responsive/RWD-002.md)

package/standard/design/responsive/tablet.md

@@ -0,0 +1,3 @@
+# Tablet
+
+Reuse mobile/desktop tokens. Avoid a third ad-hoc breakpoint set without token updates.

package/standard/design/states/async.md

@@ -0,0 +1,3 @@
+# Async
+
+Pending → success | failure | timeout | rate-limited. Offer retry when safe (STATE-002).

package/standard/design/states/conflict.md

@@ -0,0 +1,3 @@
+# Conflict
+
+Concurrent edit: show conflict and resolution path.

package/standard/design/states/empty.md

@@ -0,0 +1,3 @@
+# Empty
+
+Explain why empty + primary next action.

package/standard/design/states/error.md

@@ -0,0 +1,3 @@
+# Error
+
+Human-readable (UX-012) + recovery.

package/standard/design/states/interaction.md

@@ -0,0 +1,5 @@
+# Interaction states
+
+Cover: default, hover, focus-visible, active, disabled, selected, read-only.
+
+See STATE-001.

package/standard/design/states/loading.md

@@ -0,0 +1,3 @@
+# Loading
+
+Prefer skeletons for content-shaped regions; spinners for indeterminate short waits. Avoid infinite skeletons (see anti-patterns).

package/standard/design/states/offline.md

@@ -0,0 +1,3 @@
+# Offline
+
+Detect offline; queue or disable mutating actions with explanation.

package/standard/design/states/optimistic.md

@@ -0,0 +1,3 @@
+# Optimistic UI
+
+Rollback + error if server rejects.

package/standard/design/states/partial.md

@@ -0,0 +1,3 @@
+# Partial data
+
+Show available data + which sections failed.

package/standard/design/states/permission-denied.md

@@ -0,0 +1,3 @@
+# Permission denied
+
+STATE-003 — never a silent blank.

package/standard/design/states/rate-limited.md

@@ -0,0 +1,3 @@
+# Rate limited
+
+Say when the user can try again.

package/standard/design/states/read-only.md

@@ -0,0 +1,3 @@
+# Read-only
+
+Visually distinct from editable; don’t look disabled-confused.

package/standard/design/states/retry.md

@@ -0,0 +1,3 @@
+# Retry
+
+Safe retries only; idempotent where possible.

package/standard/design/states/skeleton.md

@@ -0,0 +1,3 @@
+# Skeleton
+
+Match layout; do not skeleton forever.

package/standard/design/states/stale.md

@@ -0,0 +1,3 @@
+# Stale
+
+Indicate outdated data and refresh affordance.

package/standard/design/states/success.md

@@ -0,0 +1,3 @@
+# Success
+
+Confirm outcome; don’t block unnecessarily.

package/standard/design/states/timeout.md

@@ -0,0 +1,3 @@
+# Timeout
+
+Explain timeout; allow retry.

package/standard/design/states/unsaved-changes.md

@@ -0,0 +1,3 @@
+# Unsaved changes
+
+STATE-004.

package/standard/design/ui/color.md

@@ -0,0 +1,6 @@
+# Color
+
+Canonical rules:
+
+- [UI-003](../../../rules/ui/UI-003.md)
+- [UI-004](../../../rules/ui/UI-004.md)

package/standard/design/ui/grids.md

@@ -0,0 +1,5 @@
+# Grids & breakpoints
+
+Define breakpoints as tokens. Align columns to a consistent grid.
+Prefer CSS Grid/Flex as in implementation — Penpot auto-layouts should map cleanly to flex/grid mental models.
+See [`responsive/`](../responsive/).

package/standard/design/ui/icons.md

@@ -0,0 +1,5 @@
+# Icons
+
+Canonical rules:
+
+- [UI-007](../../../rules/ui/UI-007.md)

package/standard/design/ui/imagery.md

@@ -0,0 +1,5 @@
+# Imagery
+
+- Meaningful images need alt text; decorative images empty alt / CSS background
+- Do not place critical text only inside images
+- Prefer real product/context imagery over abstract decoration when imagery is the message

package/standard/design/ui/layout.md

@@ -0,0 +1,5 @@
+# Layout
+
+Canonical rules:
+
+- [UI-006](../../../rules/ui/UI-006.md)

package/standard/design/ui/spacing.md

@@ -0,0 +1,5 @@
+# Spacing
+
+Canonical rules:
+
+- [UI-005](../../../rules/ui/UI-005.md)

package/standard/design/ui/typography.md

@@ -0,0 +1,6 @@
+# Typography
+
+Canonical rules:
+
+- [UI-001](../../../rules/ui/UI-001.md)
+- [UI-002](../../../rules/ui/UI-002.md)

package/standard/design/ui/visual-design.md

@@ -0,0 +1,7 @@
+# Visual design
+
+- Hierarchy beats decoration
+- Elevation/shadows from tokens
+- Radius from tokens
+- Avoid inconsistent corner radii and shadow stacks on adjacent components
+- Dark/light themes via tokens — do not fork components per theme

package/standard/design/ux/cognitive-load.md

@@ -0,0 +1,5 @@
+# Cognitive Load
+
+Canonical rules:
+
+- [UX-013](../../../rules/ux/UX-013.md)

package/standard/design/ux/errors.md

@@ -0,0 +1,6 @@
+# Errors
+
+Canonical rules:
+
+- [UX-011](../../../rules/ux/UX-011.md)
+- [UX-012](../../../rules/ux/UX-012.md)

package/standard/design/ux/feedback.md

@@ -0,0 +1,5 @@
+# Feedback
+
+Canonical rules:
+
+- [UX-010](../../../rules/ux/UX-010.md)

package/standard/design/ux/forms.md

@@ -0,0 +1,7 @@
+# Forms
+
+Canonical rules:
+
+- [UX-007](../../../rules/ux/UX-007.md)
+- [UX-008](../../../rules/ux/UX-008.md)
+- [UX-009](../../../rules/ux/UX-009.md)

package/standard/design/ux/heuristics.md

@@ -0,0 +1,14 @@
+# Heuristics checklist (NN/g-oriented)
+
+Use during design review. Severity `SHOULD` unless marked MUST elsewhere.
+
+- [ ] Status feedback after actions
+- [ ] Domain language matches users
+- [ ] Cancel / undo / Escape available where expected
+- [ ] Patterns match the rest of the product
+- [ ] Errors prevented (constraints, confirms on irreversible)
+- [ ] Options visible rather than remembered
+- [ ] Shortcuts for frequent power tasks (when relevant)
+- [ ] No decorative noise competing with the task
+- [ ] Error messages explain problem + next step
+- [ ] Help available when flows are non-obvious