svihra · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 8, 2026 · Jul 12, 2026
@@ -8,12 +8,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Added
 
+- `skills/DesignReview/SKILL.md` — capture-agnostic reviewer that verifies built UI against the `DesignPrinciples` canon from rendered artifacts (screenshot + axe-core JSON per state and viewport); hard numbers come only from axe, and axe `incomplete` or absent states report not-verified rather than pass
+- `docs/decisions/ARCH-0015 Rendered Design Review.md` — records the decision to own the review contract rather than a browser, delegating capture to a tool such as a Playwright MCP
+- `skills/DesignPrinciples/SKILL.md` — canonical cross-cutting design canon (durable foundations, WCAG-anchored hard checks, advisory non-failing thresholds), `disable-model-invocation` so it serves as a reference the other design skills cite rather than an invocable skill
+- `skills/DesignDashboard/SKILL.md` — data-UI design discipline (density, state completeness, chart-to-data-shape matching, progressive disclosure) for dashboards, admin panels, and analytics views, distinct from `DesignFrontend`'s aesthetic scope
 - `skills/BashConventions/` + `BashPatterns.md` companion — Bash pitfalls (BSD vs GNU, `set -euo pipefail` traps, subprocess env) relocated from forge-dev
 - `skills/VersionControl/GitWorktrees.md` — companion covering parallel feature work via `git worktree`, with SLSA provenance (adapted from [davila7/claude-code-templates](https://github.com/davila7/claude-code-templates) MIT under EUPL-1.2)
 - `VersionControl` now serves as the canonical home for git conventions and platform-specific repo governance (absorbing the retired forge-dev `Git` skill). forge-dev's `GitHub` skill remains distinct — it covers CI, Actions, releases, and operational `gh` workflows
 
 ### Changed
 
+- `skills/DesignFrontend/SKILL.md` — USE WHEN tightened to marketing/landing/brand-aesthetic surfaces; dashboards and analytics UI now route to `DesignDashboard`. Carries a foundations digest and cites the `DesignPrinciples` canon.
 - `skills/AdoptArtifact/SKILL.md` — removed the 3–5 initial cap and the skills-only restriction; agents are now eligible for adoption
 - `skills/ForgeAdopt/` renamed to `skills/AdoptArtifact/` for brand-neutral naming
 - `skills/RefinePrompt/` consolidates the former Prompt cluster (`AlignPrompt`, `DebrandPrompt`, `ExtractPrompt`, `MinimizePrompt`, `RescopePrompt`, `AdaptPrompts`) into one skill with six companions. Adoption sidecars collapse the per-transform `resolvedDependencies` entries to a single `RefinePrompt` SHA pin.

@@ -65,6 +65,10 @@ Skills teach AI coding tools new capabilities. Invoke them with `/SkillName` in
 | [**SystemCheck**](skills/SystemCheck/SKILL.md)                   | Ecosystem staleness and version drift checks                    |
 | [**RTK**](skills/RTK/SKILL.md)                                   | Token-optimized CLI proxy                                       |
 | [**HtmlPlayground**](skills/HtmlPlayground/SKILL.md)             | Generate single-file HTML demos comparing techniques            |
+| [**VisualIdentity**](skills/VisualIdentity/SKILL.md)             | Create shared visual profiles, previews, and CSS tokens          |
+| [**DesignPrinciples**](skills/DesignPrinciples/SKILL.md)         | Shared token, accessibility, and rendered-design canon           |
+| [**DesignFrontend**](skills/DesignFrontend/SKILL.md)             | Build distinctive profile-driven frontend interfaces            |
+| [**DesignDashboard**](skills/DesignDashboard/SKILL.md)           | Build profile-driven data-dense interfaces                       |
 | [**Brainstorming**](skills/Brainstorming/SKILL.md)               | Collaborative ideation before implementation                    |
 | [**DesignSpec**](skills/DesignSpec/SKILL.md)                      | Formal design spec from brainstorming output                    |
 | [**WritePlan**](skills/WritePlan/SKILL.md)                        | Bite-sized implementation plans with plan mode                  |

@@ -9,6 +9,15 @@ adr:
     schema: templates/forge-adr.json
     mdschema: docs/decisions/.mdschema
 
+visual_identity:
+    schema: skills/VisualIdentity/visual-profile.schema.yaml
+    example: skills/VisualIdentity/visual-profile.example.yaml
+    css_prefix: forge
+    contrast:
+        normal_text: 4.5
+        large_text: 3.0
+        ui_and_focus: 3.0
+
 agents:
     DataAnalyst:
         model: fast

@@ -0,0 +1,93 @@
+---
+title: "Rendered Design Review"
+description: "Verify built UI against the DesignPrinciples canon from rendered artifacts, owning the review contract rather than the browser that produces them"
+type: adr
+category: architecture
+tags:
+    - architecture
+    - design
+    - review
+    - accessibility
+status: accepted
+created: 2026-07-07
+updated: 2026-07-08
+author: "@N4M3Z"
+project: forge-core
+related: []
+responsible: ["@N4M3Z"]
+accountable: ["@N4M3Z"]
+consulted: []
+informed: []
+upstream: []
+---
+
+# Rendered Design Review
+
+## Context and Problem Statement
+
+The `DesignPrinciples` canon defines spec-anchored hard checks (WCAG contrast, target size) and durable foundations, but nothing verifies a built interface against them. Source-scanning cannot do it: regex over CSS-in-JS, styled-components, Tailwind arbitrary values, and React Native sees little, and no static scan computes rendered contrast, which semi-transparency, hover, and dark mode all change. A reviewer must judge the rendered result. The open question is how much infrastructure forge-core should own to make that possible without turning a markdown module into a browser-automation project.
+
+## Decision Drivers
+
+- Hard checks (contrast, target size) need computed values, not pixels judged by eye or source literals.
+- forge-core deploys markdown only; executables and browsers are a maintenance liability it has so far avoided.
+- The reviewer must not commit the flaw it polices: a happy-path-only screenshot cannot verify empty, loading, or error states.
+- Users likely already run a screenshot and accessibility tool (Playwright MCP); forge should compose with it, not duplicate it.
+
+## Considered Options
+
+1. **Source-grep reviewer** — regex or AST checks in a skill or binary. Blind on CSS-in-JS and React Native, cannot compute contrast, fires on a minority of stacks.
+2. **Own the capture** — ship a `bin/ui-shot` Playwright wrapper plus INSTALL.md producing a PNG and axe-core JSON per target. Turnkey, but inherits Chromium version drift, cross-platform browser installs, and INSTALL maintenance, and forge does not auto-deploy `bin/`. A markdown module takes on a browser dependency.
+3. **Own the contract, not the browser** — a single capture-agnostic `DesignReview` skill that consumes artifacts (PNG plus axe-core JSON per state and viewport) produced by whatever tool the user has, maps axe rule IDs to DesignPrinciples checks, and reports pass, fail, or not-verified. Pure markdown, forge-native, no dependency to maintain, composes with an existing Playwright MCP. The user must produce the artifacts; capture is not turnkey.
+
+**Risk Assessment** (option 3):
+
+- **Technical Risk**: low — a markdown skill with no runtime.
+- **Schedule Risk**: low — one skill.
+- **Ecosystem Risk**: low — depends on an external capture tool by contract, not by code.
+
+## Decision Outcome
+
+Chosen option: **own the contract, not the browser (option 3)**, because it delivers rendered verification without forge-core taking on browser automation, and it composes with capture tooling the user already runs.
+
+### Ideal implementation
+
+A `DesignReview` skill in forge-core that:
+
+- Defines a strict input contract: for each review target, a screenshot PNG plus an axe-core JSON report, named so a file maps to its target, state, and viewport, listed in a small manifest of targets by state by viewport.
+- Sources hard checks only from the axe JSON (computed contrast, target size), never from the image, with an explicit prohibition on estimating hard numbers by eye.
+- Maps axe rule IDs to DesignPrinciples checks (`color-contrast` to contrast, `target-size` to touch target).
+- Treats axe `incomplete` (contrast over gradients, images, or transformed nodes, or an unresolved background) as not-verified, never as pass.
+- Uses the screenshots for vision judgment only: structure-before-style, anti-slop tells, and state coverage.
+- Requires state targets. Given only the happy path, it reports empty, loading, and error as not-verified rather than passing.
+- Emits structured findings citing DesignPrinciples, each tagged verified-fail, verified-pass, or not-verified.
+
+### What is missing today
+
+- The `DesignReview` skill itself: the input contract, the axe-rule-to-principle map, and the reporting semantics.
+- A named artifact manifest convention (targets, states, viewports, and file naming).
+- A documented reference capture path (Playwright MCP) cited, not bundled.
+
+### Dangers
+
+- **False confidence through silence.** axe `incomplete` or a missing state reads as pass unless explicitly reported not-verified. This is the primary risk; the reporting semantics exist to close it.
+- **Vision measurement leakage.** The model may estimate contrast from the image. The skill must forbid it and route "looks wrong but axe is silent" to a not-verified suspicion, not a number.
+- **Non-determinism.** Font loading, subpixel rendering, and mid-flight animation make screenshots non-reproducible. Capture must fix the viewport, disable animation, and wait for fonts and network idle; the contract states this requirement even though a different tool satisfies it.
+- **Token cost.** States by viewports multiplies images per review; keep the default target set small.
+- **Capture gap.** With no configured capture tool the skill has nothing to read; it must degrade to an explicit no-op, not a silent pass.
+
+### Consequences
+
+- [+] Rendered verification of the DesignPrinciples canon with no browser dependency in forge-core.
+- [+] Composes with an existing Playwright MCP or any tool honoring the contract.
+- [-] Not turnkey: the user wires a capture tool and supplies targets. Mitigated by documenting one reference path and failing loudly when artifacts are absent.
+
+### Scope for the first cut
+
+Ship the `DesignReview` skill (contract, axe map, not-verified semantics), two viewports (mobile and desktop) as advisory, caller-supplied targets required. Defer bundled capture, multi-theme review, auto-discovery of states, and interaction or video review.
+
+## Links
+
+- [DesignPrinciples](../../skills/DesignPrinciples/SKILL.md) — the canon this reviewer verifies against
+- [axe-core rule descriptions](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) — rule IDs mapped to checks
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) — source of the hard checks
@@ -0,0 +1,78 @@
+---
+name: DesignDashboard
+description: "Build data-dense product UI — dashboards, admin panels, analytics views, data tables, KPI screens. USE WHEN the user asks for a dashboard, admin panel, analytics UI, data table, metrics/KPI layout, or reporting interface. For marketing, landing, or brand-aesthetic pages use DesignFrontend instead."
+version: 0.1.0
+allowed-tools: Read, Grep, Write, Edit
+---
+
+# DesignDashboard
+
+Design data UI as a systems discipline: restraint, legibility, and behavior across data shapes and non-happy-path states. This is the opposite of marketing design, density and clarity win over atmosphere and distinctiveness.
+
+## Foundations
+
+- **Structure before style.** Generic layout, not palette, is what makes UI read as templated. Fix hierarchy first.
+- **Tokens before values.** Colors, radii, spacing trace to semantic tokens; no raw hex in component code.
+- **State completeness.** Every interactive element covers default, hover, focus-visible, active, disabled, loading; every data view covers empty, loading, error.
+- **Color never alone.** Status in color is always paired with an icon, label, or shape.
+
+Hard accessibility self-checks before shipping (verify against the rendered UI, not the source): text contrast ≥ 4.5:1, UI/focus indicators ≥ 3:1, touch targets ≥ 24px (WCAG 2.2 §1.4.3, §1.4.11, §2.5.8 [WCAG]). `DesignPrinciples` holds the full cross-cutting canon, including advisory thresholds and the named-law vocabulary.
+
+## Structure first
+
+Let the data's shape drive the component, not the reverse. Prototype against real or realistic data before choosing a pattern: a single value is a stat card, a metric with 50 categories is a table, not a pie. Component choice is a data-shape decision, not an aesthetic one.
+
+If `visual-profile.yaml` exists, use its mode colors, typography, spacing, radii, focus, and motion tokens. Compile it with `VisualIdentity` when CSS is missing. Dashboard components reference `--forge-*` variables without literal identity fallbacks; changing profile must not change markup or selectors.
+
+## Layout
+
+- The sidebar is the product's spine: group nav by relevance, sink low-frequency items (settings) to the bottom, pair icons with short labels, and always mark the active item.
+- Primary metrics go where the eye lands first; secondary detail sits behind tabs, drawers, or drill-downs.
+- Cap the default view at roughly 5-9 top-level metrics. Beyond that, split — do not stack everything on one screen.
+- Use denser typography and tighter hierarchy steps than a marketing page; dashboards trade whitespace for information.
+
+## Charts
+
+Match chart type to data shape. Default to boring-but-legible over novel.
+
+| Data shape          | Chart                     |
+| ------------------- | ------------------------- |
+| Trend over time     | Line                      |
+| Category comparison | Bar                       |
+| Part of whole       | Pie / stacked bar         |
+| Single value        | Stat card / sparkline     |
+
+A pie with more than ~6 slices, a line chart on categorical data, or a single stat rendered as a table are mismatches, treat them as defects.
+
+## States
+
+"UI is what you can't see." The polish of a dashboard lives outside the populated screenshot, and these are the most verifiable gap in any dashboard PR.
+
+- **Empty:** context (why is this empty) + guidance (the next action) + a CTA when the user can resolve it.
+- **Loading:** skeletons that do not break screen-reader navigation.
+- **Error:** a recoverable message, not a blank panel.
+- **Overflow:** truncation and wrapping behavior for long labels and large numbers.
+
+## Interaction
+
+Optimistic updates (apply instantly, reconcile with the backend after) keep a dashboard feeling responsive. Surface confirmations and failures through toasts. Use modals for complex actions, popovers for lightweight settings.
+
+## Red Flags
+
+| Anti-pattern                                    | Fix                                              |
+| ----------------------------------------------- | ------------------------------------------------ |
+| Only the populated happy-path state is designed | Design empty, loading, error, and overflow first |
+| Chart type does not match the data's shape      | Re-pick from the chart table by data shape       |
+| Everything visible at once, no hierarchy        | Progressive disclosure: glance view + drill-down |
+| Sidebar has no active-item indicator            | Mark the current nav item                        |
+
+## Constraints
+
+- Produce real, working code, not mockups.
+- Keep identity-specific values in `visual-profile.yaml` or generated profile CSS, never component code.
+- Self-check the hard accessibility thresholds from the shared principles before shipping; contrast against the rendered UI, not the source literal.
+- Advisory thresholds (spacing grid, metric count, motion) parameterize to the target design system, do not hard-fail on them.
+
+## Sources
+
+[WCAG]: https://www.w3.org/TR/WCAG22/ "Web Content Accessibility Guidelines (WCAG) 2.2, W3C Recommendation"
@@ -1,19 +1,30 @@
 ---
 name: DesignFrontend
-description: "Build distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. USE WHEN the user asks for web components, pages, landing pages, dashboards, React / HTML / CSS layouts, or styling of any web UI. Not for backend or non-UI work."
+description: "Build distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. USE WHEN the user asks for a landing page, marketing site, hero, brand or premium aesthetic, or the styling and visual direction of web components. For data-dense dashboards, admin panels, and analytics UI use DesignDashboard instead. Not for backend or non-UI work."
 version: 0.1.0
 allowed-tools: Read, Grep, Write, Edit
 upstream: https://github.com/davila7/claude-code-templates/blob/main/cli-tool/components/skills/creative-design/frontend-design/SKILL.md
 ---
 
 # DesignFrontend
 
-Create distinctive, production-grade web interfaces. Commit to an aesthetic direction and execute with precision — intentionality wins over intensity, whether the direction is bold maximalism or refined minimalism.
+Create distinctive, production-grade web interfaces. Commit to an aesthetic direction and execute with precision: intentionality wins over intensity, whether the direction is bold maximalism or refined minimalism.
+
+## Foundations
+
+- **Structure before style.** Generic layout, not palette, is what makes UI read as templated. Fix hierarchy first.
+- **Tokens before values.** Colors, radii, spacing trace to semantic tokens; no raw hex in component code.
+- **State completeness.** Every interactive element covers default, hover, focus-visible, active, disabled, loading.
+- **Color never alone.** Status in color is always paired with an icon, label, or shape.
+
+Hard accessibility self-checks before shipping (verify against the rendered UI, not the source): text contrast ≥ 4.5:1, UI/focus indicators ≥ 3:1, touch targets ≥ 24px (WCAG 2.2 §1.4.3, §1.4.11, §2.5.8 [WCAG]). `DesignPrinciples` holds the full cross-cutting canon, including advisory thresholds and the named-law vocabulary.
 
 ## Direction
 
 Before coding, decide on a clear aesthetic direction. Pick one and stay true to it:
 
+If `visual-profile.yaml` exists, load it first and treat it as authoritative. Compile it with `VisualIdentity` when CSS is missing. Components reference `--forge-*` semantic variables without literal identity fallbacks. Invoke `VisualIdentity` when the request needs a new or revised cross-output identity.
+
 - Brutally minimal, maximalist chaos, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, pastel, industrial — or a point of your own choosing.
 
 Name the context, the audience, and the one thing someone will remember about the result.
@@ -45,6 +56,11 @@ No two designs should be the same. Vary themes (light/dark), fonts, aesthetics a
 ## Constraints
 
 - Produce real, working code — HTML/CSS/JS, React, Vue, etc. — not mockups
+- Keep identity-specific values in `visual-profile.yaml` or generated profile CSS, never component code
 - Maintain a single aesthetic point-of-view across the whole output; do not mix brutalist typography with pastel gradients
 - Accessibility and performance are not aesthetic concessions; they are part of production-grade
 - Iterate one visual variable per round when refining a design with the user. Bundling changes (illustration + color logic + label edits in one push) forces the user to accept or reject the whole package; they can't keep the parts that landed and discard the parts that didn't. This costs at least one extra round per bundle.
+
+## Sources
+
+[WCAG]: https://www.w3.org/TR/WCAG22/ "Web Content Accessibility Guidelines (WCAG) 2.2, W3C Recommendation"