feat(artifacts): establish Aurora visual system

plugins/artifacts/skills/create-artifacts/SKILL.md

@@ -11,6 +11,46 @@ the skill, templates, instructions, tests, or reusable tooling into that directo
 An explicit output root from the user takes precedence. `init-root` creates
 README/agent guidance symlinks to this plugin; keep their maintained contents here.
 
+## HTML Quality Goal
+
+An HTML artifact must provide a substantially better surface for understanding
+its information than the equivalent Markdown. A reader should be able to infer
+the result, status, severity, evidence shape, and next action from hierarchy,
+icons, semantic color, and compact visual summaries before reading the prose.
+HTML is not complete when it merely wraps the Markdown in styled cards.
+
+Design every region for the value it contributes at that location and size:
+
+- Lead with the conclusion and strongest proof. Keep supporting prose concise
+  and disclose forensic detail progressively.
+- Use the full semantic palette consistently: cyan for navigation and
+  information, mint for verified success, rose for risk or failure, amber for
+  caution or uncertainty, and neutral tones for context.
+- Prefer an unambiguous icon for compact actions. Every icon-only control needs
+  an accessible name and a keyboard-accessible tooltip or popover with a short
+  title or description. Keep text where an icon would make meaning less clear.
+- Use purposeful hover, focus, disclosure, and state transitions to explain
+  interactivity. Avoid decorative motion, repetitive card effects, and motion
+  that competes with the report. Respect `prefers-reduced-motion`.
+- Maintain deliberate spacing and containment. No text may overlap, collide
+  with an edge, form one-word columns, or depend on horizontal page scrolling.
+  Code and evidence may scroll inside their own bounded regions.
+- Make desktop and phone layouts independently legible. At both sizes, inspect
+  the header, hero, metrics, navigation, expanded details, tables, code, and the
+  longest realistic identifier or evidence line.
+
+Use [Design and Template Parity](references/design.md) for the visual contract.
+If the visual result is not faster to scan and easier to understand than the
+source Markdown, revise it before delivery.
+
+Share the Aurora shell, tokens, accessibility behavior, and component patterns
+across artifact types, while giving every type its own information architecture.
+A report centers findings and proof; a proposal centers a decision and its
+alternatives; a spec centers requirements and acceptance; research centers
+confidence and falsifiers; a session centers chronology and handoff; docs center
+durable rules; and a PR report centers lifecycle readiness. Do not ship one
+generic page with labels changed for each type.
+
 ## Choose the Project and Template
 
 Resolve the artifact's actual subject repository as `owner/repository`, using the

plugins/artifacts/skills/create-artifacts/references/design.md

@@ -49,6 +49,73 @@ Preserve dark/light contrast, reduced-motion behavior, readable code wrapping
 or scrolling, native keyboard-operated details, and tables on narrow screens.
 Body prose stays in Inter; monospace is reserved for code and identifiers.
 
+### Visual comprehension contract
+
+Aurora HTML artifacts are information interfaces, not decorated documents.
+Their composition must make the outcome, confidence, severity, progress, and
+proof boundaries visible before a reader parses the prose. Prefer compact
+metrics, state indicators, status rails, diagrams, and progressive disclosure
+when they replace repeated explanation without losing evidence.
+
+Use Aurora color by meaning across the whole page: cyan for information and
+navigation, mint for verified success, rose for risk and failure, amber for
+caution and unknowns, and frost neutrals for supporting context. Do not tint
+every surface. Reserve color for signals so it remains useful at a glance.
+
+Keep display headings balanced and contained, with a practical maximum near
+66px on wide screens and 44px on phones. Body lines should normally stay within
+68 characters. Layout columns must use `minmax(0, …)` where long identifiers or
+evidence could otherwise force overflow. Never allow narrow columns to turn
+sentences into stacks of single words. Evidence and code scroll inside bounded
+regions rather than widening the page.
+
+Separate metric cards with space; do not use borders or pseudo-elements that
+visually connect unrelated cards. Give each metric a semantic accent and enough
+padding for its longest expected label. Every page region must earn its area:
+remove repeated prose, collapse secondary evidence, and let the primary result
+occupy the strongest visual position.
+
+Use hover and focus feedback on interactive elements. Icon-only controls are
+preferred when the icon is familiar and the surrounding context is clear; they
+must expose an accessible name and a keyboard-accessible tooltip or popover.
+Keep a text label when removing it would slow comprehension. Use transitions
+for disclosure, selection, and direct manipulation, and provide an equivalent
+reduced-motion state.
+
+Before delivery, inspect a representative filled artifact at desktop and phone
+widths. Check the top and bottom of every section, expanded details, the longest
+title, every control and tooltip, code and evidence overflow, table behavior,
+focus visibility, and reduced motion. A template scaffold alone is insufficient
+visual proof because placeholder lengths do not represent real content.
+
+### Aligned artifact families
+
+Every Aurora HTML type shares the full-bleed identity bar, concise outcome hero,
+semantic metric strip, icon vocabulary, sticky or compact wayfinding, accessible
+disclosure and filtering, bounded evidence surfaces, responsive rules, and the
+same token meanings. The primary visual story remains specific to the artifact:
+
+| Type | Primary visual story | Secondary destination |
+| --- | --- | --- |
+| Reports | Findings, causal trace, and observed proof | Excluded claims |
+| PR reports | Six-stage lifecycle readiness and evidence graph | Handoff state |
+| Proposals | Recommendation and decision tradeoffs | Rejected alternatives |
+| Specs | Requirements and acceptance checks | Explicit boundaries |
+| Research | Confidence-weighted findings | Uncertainty and falsifiers |
+| Sessions | Chronology, actions, and results | Open work and handoff |
+| Docs | Durable rules and verification | Exceptions and non-goals |
+
+Navigation must move between those meaningful regions or change the visible
+information set. A control that produces no visible state change, useful empty
+state, result count, or new destination is unfinished. Filters expose pressed
+state and announce the visible record count. Zero-result filters explain what
+is absent and offer a clear way back to the complete set.
+
+Reports use Overview, Findings, and Evidence as their primary navigation. Do
+not add category filters when the report has too few findings for filtering to
+provide a meaningful reduction. A short report should spend that space on its
+scope and evidence boundary instead.
+
 ## Updating the Snapshot
 
 Update design resources deliberately against an inspected Aurora revision.

plugins/artifacts/tests/test_artifacts.py

@@ -96,6 +96,52 @@ def test_every_html_family_has_embedded_fonts_and_stable_pr_sections(self):
         ids=lambda family:re.findall(r'<section[^>]*\bid="([^"]+)"',template_path('pr-reports',family).read_text())
         self.assertEqual(ids('aurora'),ids('unraid'))
 
+    def test_every_aurora_html_template_uses_visual_contract_v2(self):
+        for kind in ['reports','pr-reports','proposals','specs','research','sessions','docs']:
+            source=template_path(kind,'aurora').read_text()
+            self.assertIn('Aurora artifact visual contract v2',source)
+            self.assertIn('--stat-color:var(--aurora-accent-pink)',source)
+            self.assertIn('--stat-color:var(--aurora-success)',source)
+            self.assertIn('--stat-color:var(--aurora-warn)',source)
+            self.assertIn('grid-template-columns:minmax(300px,.72fr) minmax(0,1.28fr)',source)
+            self.assertIn('@media(max-width:620px)',source)
+            self.assertIn('button[aria-label]:focus-visible:after',source)
+            self.assertIn('@media(prefers-reduced-motion:reduce)',source)
+
+    def test_aurora_templates_share_shell_but_keep_useful_navigation(self):
+        interactive=['proposals','specs','research','sessions','docs']
+        for kind in interactive:
+            source=template_path(kind,'aurora').read_text()
+            self.assertEqual(source.count('class="header-nav"'),1)
+            self.assertEqual(source.count('class="artifact-nav"'),1)
+            self.assertEqual(source.count('class="metric-icon"'),4)
+            self.assertGreaterEqual(source.count('class="section-icon"'),2)
+            self.assertIn('class="filter-feedback" role="status"',source)
+            self.assertIn('aria-pressed',source)
+            self.assertIn('visible ${visible===1?"record":"records"}',source)
+        report=template_path('reports','aurora').read_text()
+        self.assertEqual(report.count('class="artifact-nav"'),1)
+        self.assertNotIn('<div class="filters">',report)
+        self.assertNotIn('class="filter-feedback" role="status"',report)
+        self.assertIn('href="#artifact-evidence"',report)
+        pr=template_path('pr-reports','aurora').read_text()
+        self.assertEqual(pr.count('class="metric-icon"'),4)
+        self.assertEqual(pr.count('class="phasehead"'),6)
+        self.assertIn('aria-label="PR report stages"',pr)
+
+    def test_aurora_header_is_full_bleed_and_content_stays_contained(self):
+        source=(SKILL/'assets/aurora/artifact-components.css').read_text()
+        self.assertIn('width:100vw;margin-left:calc(50% - 50vw)',source)
+        self.assertIn('.excluded{margin-top:',source)
+        self.assertIn('.excluded-grid article{position:relative;min-width:0',source)
+        self.assertIn('.filter-feedback.visible{display:grid}',source)
+
+    def test_artifact_skill_sets_html_comprehension_goal(self):
+        source=(SKILL/'SKILL.md').read_text()
+        self.assertIn('substantially better surface for understanding',source)
+        self.assertIn('keyboard-accessible tooltip or popover',source)
+        self.assertIn('No text may overlap',source)
+
     def test_generic_plan_header_and_discovery_output_root(self):
         from _app.validate import check_plan
         self.assertNotIn('PLAN-HEADER',{i['rule'] for i in check_plan('plans/example.md',template_path('plans','aurora').read_text())})