@schneiderjoseph/devia 0.1.0

package/rules/ui/UI-006.md

@@ -0,0 +1,40 @@
+---
+id: UI-006
+title: Consistent page chrome
+severity: SHOULD
+status: active
+priority: P2
+domain: ui
+source:
+  - Carbon
+  - Atlassian
+applies_to:
+  - layout
+  - navigation
+success_criteria:
+  []
+requirement: >
+  App shells SHOULD reuse one nav/header/content frame pattern.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UI-006 — Consistent page chrome
+
+**Requirement:** App shells SHOULD reuse one nav/header/content frame pattern.
+
+**Bad:** Every page invents a new header height and nav placement.
+
+**Good:** Shared shell component/template.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/ui/UI-007.md

@@ -0,0 +1,41 @@
+---
+id: UI-007
+title: Icon-only controls named
+severity: MUST
+status: active
+priority: P0
+domain: ui
+source:
+  - WCAG-2.2
+  - WAI-ARIA-APG
+applies_to:
+  - button
+  - link
+success_criteria:
+  - "4.1.2"
+requirement: >
+  Icon-only controls MUST have an accessible name (aria-label, aria-labelledby, or visually hidden text).
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# UI-007 — Icon-only controls named
+
+**Requirement:** Icon-only controls MUST have an accessible name (aria-label, aria-labelledby, or visually hidden text).
+
+**Bad:** Trash icon button with no name.
+
+**Good:** aria-label="Delete order".
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `documented-only`

package/rules/ux/UX-001.md

@@ -0,0 +1,41 @@
+---
+id: UX-001
+title: One primary action per view
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - NN/g
+applies_to:
+  - page
+  - view
+  - dialog
+success_criteria:
+  []
+requirement: >
+  Each primary view MUST expose a clear primary action (or explicitly be read-only).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-001 — One primary action per view
+
+**Requirement:** Each primary view MUST expose a clear primary action (or explicitly be read-only).
+
+**Bad:** Three equally weighted CTAs competing in the header.
+
+**Good:** One primary CTA; secondary actions visually quieter.
+
+## Validation
+
+- Visual hierarchy review
+- Task success / heuristic review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-002.md

@@ -0,0 +1,41 @@
+---
+id: UX-002
+title: System status visible
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - NN/g
+applies_to:
+  - forms
+  - async
+  - buttons
+success_criteria:
+  []
+requirement: >
+  After user-initiated actions that take noticeable time or change data, the UI MUST show progress or confirmation.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# UX-002 — System status visible
+
+**Requirement:** After user-initiated actions that take noticeable time or change data, the UI MUST show progress or confirmation.
+
+**Bad:** Save with no toast/spinner/inline confirmation.
+
+**Good:** Pending state + success/error outcome.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-003.md

@@ -0,0 +1,39 @@
+---
+id: UX-003
+title: Navigation mirrors user mental model
+severity: SHOULD
+status: active
+priority: P2
+domain: ux
+source:
+  - NN/g
+  - GOV.UK
+applies_to:
+  - navigation
+success_criteria:
+  []
+requirement: >
+  Top-level nav labels SHOULD match user tasks/objects, not internal org charts.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-003 — Navigation mirrors user mental model
+
+**Requirement:** Top-level nav labels SHOULD match user tasks/objects, not internal org charts.
+
+**Bad:** Nav: ‘Module A / Module B’ from engineering.
+
+**Good:** Nav: task/object names users recognize.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/ux/UX-004.md

@@ -0,0 +1,39 @@
+---
+id: UX-004
+title: Depth with orientation
+severity: SHOULD
+status: active
+priority: P2
+domain: ux
+source:
+  - GOV.UK
+applies_to:
+  - navigation
+  - page
+success_criteria:
+  []
+requirement: >
+  Hierarchies deeper than two levels SHOULD provide orientation (breadcrumbs, clear titles, back).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-004 — Depth with orientation
+
+**Requirement:** Hierarchies deeper than two levels SHOULD provide orientation (breadcrumbs, clear titles, back).
+
+**Bad:** Deep page with only a logo home link.
+
+**Good:** Title + breadcrumb or explicit back to parent context.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/ux/UX-005.md

@@ -0,0 +1,40 @@
+---
+id: UX-005
+title: Current location indicated
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - WCAG-2.2
+  - NN/g
+applies_to:
+  - navigation
+success_criteria:
+  - "2.4.8"
+requirement: >
+  Primary navigation MUST indicate the current section/page.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# UX-005 — Current location indicated
+
+**Requirement:** Primary navigation MUST indicate the current section/page.
+
+**Bad:** All nav items look identical while on a child page.
+
+**Good:** Active state on current section; page title / h1 align.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-006.md

@@ -0,0 +1,40 @@
+---
+id: UX-006
+title: Skip to content
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - WCAG-2.2
+applies_to:
+  - web
+  - navigation
+success_criteria:
+  - "2.4.1"
+requirement: >
+  Sites/apps with repeated chrome MUST provide a skip link or equivalent landmark bypass.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# UX-006 — Skip to content
+
+**Requirement:** Sites/apps with repeated chrome MUST provide a skip link or equivalent landmark bypass.
+
+**Bad:** 100 tabs through the mega-nav every page load.
+
+**Good:** Skip link or landmark structure that works with SR/keyboard.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-007.md

@@ -0,0 +1,44 @@
+---
+id: UX-007
+title: Persistent accessible labels
+severity: MUST
+status: active
+priority: P0
+domain: ux
+source:
+  - WCAG-2.2
+  - GOV.UK
+applies_to:
+  - input
+  - select
+  - textarea
+  - forms
+success_criteria:
+  - "1.3.1"
+  - "3.3.2"
+requirement: >
+  Every field MUST have a persistent accessible label. Placeholder-only labeling is forbidden.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# UX-007 — Persistent accessible labels
+
+**Requirement:** Every field MUST have a persistent accessible label. Placeholder-only labeling is forbidden.
+
+**Bad:** placeholder="Email" with no label.
+
+**Good:** Visible label associated via for/id or wrapping; placeholder optional hint only.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `documented-only`

package/rules/ux/UX-008.md

@@ -0,0 +1,41 @@
+---
+id: UX-008
+title: Field errors identifiable and actionable
+severity: MUST
+status: active
+priority: P0
+domain: ux
+source:
+  - WCAG-2.2
+  - GOV.UK
+applies_to:
+  - forms
+success_criteria:
+  - "3.3.1"
+  - "3.3.3"
+requirement: >
+  Validation errors MUST identify the field, describe the problem, and how to fix it.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# UX-008 — Field errors identifiable and actionable
+
+**Requirement:** Validation errors MUST identify the field, describe the problem, and how to fix it.
+
+**Bad:** Toast: ‘Invalid form’.
+
+**Good:** Inline error + focus move to first error; summary for long forms.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `documented-only`

package/rules/ux/UX-009.md

@@ -0,0 +1,39 @@
+---
+id: UX-009
+title: Required fields indicated in text
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - WCAG-2.2
+  - GOV.UK
+applies_to:
+  - forms
+success_criteria:
+  - "1.4.1"
+requirement: >
+  Required fields MUST be indicated in text (not color alone).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-009 — Required fields indicated in text
+
+**Requirement:** Required fields MUST be indicated in text (not color alone).
+
+**Bad:** Red asterisk only, unexplained.
+
+**Good:** ‘Required’ in legend/label text (asterisk OK if explained once).
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-010.md

@@ -0,0 +1,40 @@
+---
+id: UX-010
+title: Complete UI states for data views
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - NN/g
+applies_to:
+  - page
+  - table
+  - list
+success_criteria:
+  []
+requirement: >
+  Key screens MUST define empty, loading, error, and success/populated states where data can be absent or fail.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-010 — Complete UI states for data views
+
+**Requirement:** Key screens MUST define empty, loading, error, and success/populated states where data can be absent or fail.
+
+**Bad:** Blank white area while fetching; crash on error.
+
+**Good:** Skeleton/spinner; empty + CTA; recoverable error.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-011.md

@@ -0,0 +1,40 @@
+---
+id: UX-011
+title: Confirm irreversible actions
+severity: MUST
+status: active
+priority: P0
+domain: ux
+source:
+  - NN/g
+  - GOV.UK
+applies_to:
+  - buttons
+  - dialogs
+success_criteria:
+  []
+requirement: >
+  Destructive/irreversible actions MUST require confirmation or undo.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-011 — Confirm irreversible actions
+
+**Requirement:** Destructive/irreversible actions MUST require confirmation or undo.
+
+**Bad:** Delete permanently on single click.
+
+**Good:** Confirm dialog with consequence stated, or toast undo window.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `documented-only`

package/rules/ux/UX-012.md

@@ -0,0 +1,40 @@
+---
+id: UX-012
+title: Human-readable errors
+severity: MUST
+status: active
+priority: P1
+domain: ux
+source:
+  - WCAG-2.2
+  - GOV.UK
+applies_to:
+  - alerts
+  - forms
+success_criteria:
+  - "3.3.3"
+requirement: >
+  User-facing errors MUST NOT expose stack traces, SQL, or internal codes as the only message.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-012 — Human-readable errors
+
+**Requirement:** User-facing errors MUST NOT expose stack traces, SQL, or internal codes as the only message.
+
+**Bad:** PQXZ_99 constraint violation.
+
+**Good:** Plain language + optional reference id for support.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/ux/UX-013.md

@@ -0,0 +1,39 @@
+---
+id: UX-013
+title: Progressive disclosure
+severity: SHOULD
+status: active
+priority: P2
+domain: ux
+source:
+  - NN/g
+applies_to:
+  - forms
+  - page
+success_criteria:
+  []
+requirement: >
+  Advanced or rare options SHOULD be progressive, not dumped equally with core fields.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# UX-013 — Progressive disclosure
+
+**Requirement:** Advanced or rare options SHOULD be progressive, not dumped equally with core fields.
+
+**Bad:** 40 equal fields on one screen for a simple task.
+
+**Good:** Core fields first; advanced collapsed or stepped.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/schema/README.md

@@ -0,0 +1,19 @@
+# Schemas
+
+JSON Schema for the file shapes devia reads and writes. They are the contract; the validators
+enforce them.
+
+| Schema | Describes | Enforced by |
+|---|---|---|
+| [`rule.schema.json`](rule.schema.json) | A rule file's frontmatter | `scripts/validate-rules.mjs`, `src/lib/rules.mjs` |
+| [`project-config.schema.json`](project-config.schema.json) | `.devia/devia.json` | `devia validate` (required keys today — see the debt register) |
+| [`waiver.schema.json`](waiver.schema.json) | A time-boxed exception | `devia check` (expiry) |
+| [`checklist.schema.json`](checklist.schema.json) | A machine-readable checklist | — |
+| [`component.schema.json`](component.schema.json) | A design-system component record | — |
+| [`token.schema.json`](token.schema.json) | A design token | — |
+
+Schema versions live in [`../VERSION`](../VERSION). A change to a required field is a breaking
+change: bump the version and say in [`../CHANGELOG.md`](../CHANGELOG.md) what adopters must do.
+
+A schema listed with no enforcement is documentation, and is marked as such rather than implied
+to be checked.

package/schema/checklist.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Checklist",
+  "type": "object",
+  "required": [
+    "id",
+    "items"
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "text"
+        ],
+        "properties": {
+          "text": {
+            "type": "string"
+          },
+          "rule_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}