arkaos 4.28.0 → 4.30.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.28.0 — 89 agents, 17 departments, 329 skills, 297 commands, 16 ADRs.
+> v4.30.0 — 89 agents, 17 departments, 329 skills, 297 commands, 16 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.28.0
+4.30.0

package/arka/skills/refine/SKILL.md

@@ -73,6 +73,13 @@ input clear enough to build the right thing."*
 - Be critical: if the request is technically wrong or would ship a worse
   product, challenge it here (pushback protocol, `arkaos-not-yes-man`)
   before compiling.
+- **Redesign asks have hard boundaries.** When the rough idea is
+  "redesign X", the compiled prompt states them explicitly: preserve
+  routes, information architecture, and copy INTENT — the visual layer is
+  the scope; a full rebuild (structure or content changes) requires its
+  own explicit confirmation, never rides along silently. The visual loop
+  after dispatch belongs to `brand/design-review` (slop gates + register
+  discipline in its `references/`).
 
 ## Related
 

package/config/claude-agents/brand-director.md

@@ -48,4 +48,4 @@ You are Valentina, Creative Director of the brand squad (Tier 1). What drives yo
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: Primal Branding (Hanlon), StoryBrand (Miller), Brand Archetypes (Jung), Wheeler Process, Atomic Design (Frost), Nielsen Heuristics, Dieter Rams 10 Principles, Double Diamond. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: Primal Branding (Hanlon), StoryBrand (Miller), Brand Archetypes (Jung), Wheeler Process, Atomic Design (Frost), Nielsen Heuristics, Dieter Rams 10 Principles, Double Diamond, Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/conversion-strategist.md

@@ -47,4 +47,4 @@ You are Ines, Conversion Strategist of the landing squad (Tier 1). What drives y
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: Grand Slam Offer (Hormozi), Value Ladder (Brunson), Schwartz 5 Levels, PLF (Walker), AIDA/PAS/PASTOR, ResearchXL CRO, Crossing the Chasm. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: Grand Slam Offer (Hormozi), Value Ladder (Brunson), Schwartz 5 Levels, PLF (Walker), AIDA/PAS/PASTOR, ResearchXL CRO, Crossing the Chasm, Hallmark macrostructures (21 page shapes) + component archetype cookbook (50). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/design-ops-lead.md

@@ -48,4 +48,4 @@ You are Iris, Design Ops Lead of the brand squad (Tier 1). What drives you: Make
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: Atomic Design (Frost), Design Tokens Community Group, WCAG 2.2, Style Dictionary, shadcn/ui conventions, Tailwind CSS configuration. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: Atomic Design (Frost), Design Tokens Community Group, WCAG 2.2, Style Dictionary, shadcn/ui conventions, Tailwind CSS configuration, Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/extraction-script-writer.md

@@ -48,4 +48,4 @@ You are Nia, Design Extraction Engineer of the brand squad (Tier 2). What drives
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: W3C Design Tokens spec, Style Dictionary, Tailwind CSS token format, shadcn/ui CSS variable convention, DTCG JSON schema. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: W3C Design Tokens spec, Style Dictionary, Tailwind CSS token format, shadcn/ui CSS variable convention, DTCG JSON schema, Design DNA study protocol (URL/screenshot extraction, SSRF-safe). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/frontend-dev.md

@@ -48,4 +48,4 @@ You are Diana, Senior Frontend Developer of the dev squad (Tier 2). What drives
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: Atomic Design, Component-Driven Development, Laws of UX, Nielsen Heuristics, CWV Optimization, ArkaOS Motion System, Design Tokens (DTCG), runtime:frontend-design (Anthropic skill), runtime:ui-ux-pro-max (community skill). A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: Atomic Design, Component-Driven Development, Laws of UX, Nielsen Heuristics, CWV Optimization, ArkaOS Motion System, Design Tokens (DTCG), Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product), Hallmark macrostructures (21 page shapes) + component archetype cookbook (50), runtime:frontend-design (Anthropic skill), runtime:ui-ux-pro-max (community skill). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/landing-cro-specialist.md

@@ -47,4 +47,4 @@ You are Hugo, CRO Specialist of the landing squad (Tier 2). What drives you: Und
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: ResearchXL (Peep Laja / CXL), PIE/ICE Prioritization, Baymard UX Guidelines, Statistical Significance Testing, Heuristic Analysis. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: ResearchXL (Peep Laja / CXL), PIE/ICE Prioritization, Baymard UX Guidelines, Statistical Significance Testing, Heuristic Analysis, Hallmark macrostructures (21 page shapes) + component archetype cookbook (50). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/ux-designer.md

@@ -47,4 +47,4 @@ You are Sofia D., UX/UI Designer of the brand squad (Tier 2). What drives you: C
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: Don Norman — Human-Centered Design (affordances, signifiers, feedback, mapping), Nielsen 10 Heuristics, Steve Krug — Don't Make Me Think (self-evidence, guerrilla testing), Dieter Rams — 10 Principles of Good Design, Laws of UX (Yablonski), Garrett's 5 Planes (strategy, scope, structure, skeleton, surface), Design Studio (Gothelf — collaborative multidisciplinary ideation, sketch → critique → converge), Double Diamond, Design Thinking (IDEO), Atomic Design, WCAG 2.1 AA, Two-Part Conversion Formula, Microinteractions (trigger-rules-feedback-loops), runtime:frontend-design (Anthropic skill). A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: Don Norman — Human-Centered Design (affordances, signifiers, feedback, mapping), Nielsen 10 Heuristics, Steve Krug — Don't Make Me Think (self-evidence, guerrilla testing), Dieter Rams — 10 Principles of Good Design, Laws of UX (Yablonski), Garrett's 5 Planes (strategy, scope, structure, skeleton, surface), Design Studio (Gothelf — collaborative multidisciplinary ideation, sketch → critique → converge), Double Diamond, Design Thinking (IDEO), Atomic Design, WCAG 2.1 AA, Two-Part Conversion Formula, Microinteractions (trigger-rules-feedback-loops), Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product), runtime:frontend-design (Anthropic skill). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/ux-strategist.md

@@ -48,4 +48,4 @@ You are Júlia, UX Strategist of the brand squad (Tier 2). What drives you: Brid
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: 4 Elements of UX Strategy (Levy), Blue Ocean / Value Innovation, Provisional Personas, Lean UX. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: 4 Elements of UX Strategy (Levy), Blue Ocean / Value Innovation, Provisional Personas, Lean UX, Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/visual-designer.md

@@ -47,4 +47,4 @@ You are Isabel, Visual Designer of the brand squad (Tier 2). What drives you: Cr
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: Dieter Rams 10 Principles, Atomic Design (visual layer), Color Theory, Typography Hierarchy, Brand Identity Process (Wheeler), ArkaOS Design Tokens, WCAG AA contrast, runtime:frontend-design (Anthropic skill), runtime:ui-ux-pro-max (community skill). A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: Dieter Rams 10 Principles, Atomic Design (visual layer), Color Theory, Typography Hierarchy, Brand Identity Process (Wheeler), ArkaOS Design Tokens, WCAG AA contrast, Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product), Hallmark macrostructures (21 page shapes) + component archetype cookbook (50), runtime:frontend-design (Anthropic skill), runtime:ui-ux-pro-max (community skill). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/claude-agents/wcag-auditor.md

@@ -48,4 +48,4 @@ You are Oren, Accessibility Auditor of the brand squad (Tier 2). What drives you
 
 ## Grounding
 
-Recommendations cite the framework behind them — yours: WCAG 2.2, WAI-ARIA 1.2, ATAG 2.0, EAA / EN 301 549, axe-core ruleset, Section 508. A recommendation without a named framework or reference is an opinion; label it as such.
+Recommendations cite the framework behind them — yours: WCAG 2.2, WAI-ARIA 1.2, ATAG 2.0, EAA / EN 301 549, axe-core ruleset, Section 508, Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V), Impeccable design laws + registers (brand vs product). A recommendation without a named framework or reference is an opinion; label it as such.

package/config/skills-provenance.yaml

@@ -60,6 +60,37 @@
 baseline_date: 2026-07-14
 
 derived:
+  # Design absorption campaign W1 — slop gates, anti-patterns, critique
+  # protocol and registers derived from nutlope/hallmark (MIT, primary
+  # source in frontmatter) and pbakaus/impeccable (Apache-2.0, second
+  # source recorded in docs/THIRD-PARTY-NOTICES.md). Both skills were
+  # reclassified OUT of first_party deliberately: their bodies now carry
+  # substantial ported content.
+  departments/brand/skills/design-review:
+    origin: community
+    source: https://github.com/nutlope/hallmark
+    license: MIT
+  departments/brand/skills/ux-audit:
+    origin: community
+    source: https://github.com/nutlope/hallmark
+    license: MIT
+  # Design absorption campaign W2 — structural variety (macrostructures,
+  # component cookbook), design DNA study, design.md spec, OKLCH theme
+  # construction and motion recipes. page-architect keeps its Corey
+  # Haines primary source (dual-source: hallmark recorded in
+  # docs/THIRD-PARTY-NOTICES.md, stop-slop precedent).
+  departments/brand/skills/design-system:
+    origin: community
+    source: https://github.com/nutlope/hallmark
+    license: MIT
+  departments/brand/skills/colors:
+    origin: community
+    source: https://github.com/nutlope/hallmark
+    license: MIT
+  departments/dev/skills/animated-website:
+    origin: community
+    source: https://github.com/nutlope/hallmark
+    license: MIT
   # Marketing skills integration campaign — derived from
   # coreyhaines31/marketingskills (MIT). Frontmatter metadata must match
   # each entry field-for-field (test_registry_matches_frontmatter_field_for_field).
@@ -271,16 +302,12 @@ first_party:
   - arka/skills/research
   - departments/brand
   - departments/brand/skills/archetype-finder
-  - departments/brand/skills/colors
-  - departments/brand/skills/design-review
-  - departments/brand/skills/design-system
   - departments/brand/skills/identity-system
   - departments/brand/skills/logo-brief
   - departments/brand/skills/mockup-generate
   - departments/brand/skills/naming-evaluate
   - departments/brand/skills/positioning-statement
   - departments/brand/skills/primal-audit
-  - departments/brand/skills/ux-audit
   - departments/brand/skills/voice-guide
   - departments/brand/skills/wireframe
   - departments/community
@@ -322,7 +349,6 @@ first_party:
   - departments/dev/skills/agent-workflow
   - departments/dev/skills/ai-assisted-dev
   - departments/dev/skills/ai-security
-  - departments/dev/skills/animated-website
   - departments/dev/skills/api-design
   - departments/dev/skills/app-test
   - departments/dev/skills/architecture-design

package/departments/brand/agents/brand-director.yaml

@@ -66,6 +66,8 @@ expertise:
     - Nielsen Heuristics
     - Dieter Rams 10 Principles
     - Double Diamond
+    - Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V)
+    - Impeccable design laws + registers (brand vs product)
   depth: master
   years_equivalent: 14
 

package/departments/brand/agents/design-ops/design-ops-lead.yaml

@@ -64,6 +64,8 @@ expertise:
     - Style Dictionary
     - shadcn/ui conventions
     - Tailwind CSS configuration
+    - Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V)
+    - Impeccable design laws + registers (brand vs product)
   depth: master
   years_equivalent: 12
 

package/departments/brand/agents/design-ops/extraction-script-writer.yaml

@@ -60,6 +60,7 @@ expertise:
     - Tailwind CSS token format
     - shadcn/ui CSS variable convention
     - DTCG JSON schema
+    - Design DNA study protocol (URL/screenshot extraction, SSRF-safe)
   depth: expert
   years_equivalent: 9
 

package/departments/brand/agents/design-ops/wcag-auditor.yaml

@@ -62,6 +62,8 @@ expertise:
     - EAA / EN 301 549
     - axe-core ruleset
     - Section 508
+    - Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V)
+    - Impeccable design laws + registers (brand vs product)
   depth: master
   years_equivalent: 11
 

package/departments/brand/agents/ux-designer.yaml

@@ -70,6 +70,8 @@ expertise:
     - WCAG 2.1 AA
     - Two-Part Conversion Formula
     - Microinteractions (trigger-rules-feedback-loops)
+    - Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V)
+    - Impeccable design laws + registers (brand vs product)
     - runtime:frontend-design (Anthropic skill)
   knowledge_sources:
     - "[[Area 02 - Design]]"

package/departments/brand/agents/ux-strategist.yaml

@@ -54,6 +54,8 @@ expertise:
     - Blue Ocean / Value Innovation
     - Provisional Personas
     - Lean UX
+    - Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V)
+    - Impeccable design laws + registers (brand vs product)
   knowledge_sources:
     - "[[Personas/Jaime Levy]]"
     - "[[4 Elementos Centrais da UX Strategy]]"

package/departments/brand/agents/visual-designer.yaml

@@ -57,6 +57,9 @@ expertise:
     - Brand Identity Process (Wheeler)
     - ArkaOS Design Tokens
     - WCAG AA contrast
+    - Hallmark slop gates (58) + pre-emit critique (P/H/E/S/R/V)
+    - Impeccable design laws + registers (brand vs product)
+    - Hallmark macrostructures (21 page shapes) + component archetype cookbook (50)
     - runtime:frontend-design (Anthropic skill)
     - runtime:ui-ux-pro-max (community skill)
   depth: expert

package/departments/brand/references/uiux-knowledge-and-tools.md

@@ -6,7 +6,8 @@
 >
 > Read this BEFORE any UI/UX work. It defines the non-negotiable KB-first
 > rule, the canonical knowledge sources, the concrete design tokens, the
-> motion system, the new tooling, and the squad validation order.
+> motion system, the new tooling, the squad validation order, the canonical
+> reflex-reject lists (§11) and the hard design laws (§12).
 
 ---
 
@@ -131,8 +132,13 @@ write material findings back to `[[Area 02 - Design]]`:
 - Laws of UX (each law)
 - Dieter Rams' 10 principles
 - Atomic Design (full atoms→pages)
-- Microinteractions (trigger→rules→feedback→loops/modes)
-- Color theory & typography science (OKLCH, harmony, modular scale)
+- Microinteractions (trigger→rules→feedback→loops/modes) —
+  **filled in-repo**: 15 recipes + 20 tells in
+  `departments/dev/skills/animated-website/references/motion-recipes.md`.
+- Color theory & typography science (OKLCH, harmony, modular scale) —
+  **partially filled in-repo**: hard floors/ceilings now live in §12 and
+  the reflex-reject discipline in §11; deeper craft references live under
+  `departments/brand/skills/design-review/references/`.
 - Gestalt & visual hierarchy (F/Z scanning, proximity, contrast)
 
 ---
@@ -168,6 +174,23 @@ for any other brief?"* If yes, revise and state what changed and why.
 Quality floor, never announced: responsive to mobile, visible keyboard
 focus, `prefers-reduced-motion` respected, WCAG AA contrast.
 
+**Pre-emit critique (scored — hallmark protocol).** Before handing back
+any design artifact, score it 1–5 on six axes:
+
+| Axis | Question |
+|---|---|
+| **P** Philosophy | Does the design have a stated POV the brief earns? |
+| **H** Hierarchy | Does the eye land where the content says it should? |
+| **E** Execution | Are spacing, contrast, states, and breakpoints finished? |
+| **S** Specificity | Does this look like *this brief* — or a generic page? |
+| **R** Restraint | Is every bold move deliberate; is everything else quiet? |
+| **V** Variety | Does it differ structurally from the previous output? |
+
+Any axis **< 3 triggers a revision pass** — never ship and explain.
+Stamp the six scores in the artifact via the `[arka:design-dna]` companion
+stamp (§9). The 58 pass/fail slop gates that operationalize this rubric
+live in `departments/brand/skills/design-review/references/slop-test.md`.
+
 ## 9. Design Marker Contract (`[arka:design]`)
 
 Every UI/design-producing turn MUST emit the structured marker on its own
@@ -192,6 +215,21 @@ A bare `[arka:design] <token>` is a LEGACY marker: tolerated in WARN mode,
 counted separately in telemetry, and treated as missing once the frontend
 gate goes hard.
 
+**Companion stamp `[arka:design-dna]` (informational).** Design-producing
+work additionally stamps the first non-empty line of produced CSS with:
+
+```
+/* [arka:design-dna] macrostructure=<name> genre=<genre> anchor=<oklch|hex> display=<font> body=<font> critique=P#H#E#S#R#V# */
+```
+
+Key=value, single line, greppable. It records the structural choice, the
+palette anchor, the type pairing, and the six pre-emit critique scores
+(§8), and feeds the structural-diversification rule (consecutive outputs
+must differ on at least one axis; project memory at
+`.arka/design/log.json`). This stamp is **NOT parsed by the frontend gate**
+(`core/workflow/frontend_gate.py`) and carries no gate semantics — the
+structured `[arka:design]` marker above remains the only enforced line.
+
 ## 10. Aesthetic Directions Catalog (optional, curated)
 
 When a project has NO design system yet and the brief leaves the visual
@@ -207,3 +245,160 @@ job: load `gsap-core` + `gsap-timeline` for any animation work,
 `gsap-scrolltrigger`/`gsap-plugins` as the work demands, `gsap-react` on
 React, and treat `gsap-performance` as the review bar
 (`npx skills add https://github.com/greensock/gsap-skills` when absent).
+
+Four in-repo theme specs (hallmark-derived, opt-in seeds like the TypeUI
+directions — never the final system) live at
+`departments/brand/skills/design-system/references/themes/`:
+
+`carnival` — loud-decorative, multi-accent riso energy · `cobalt` —
+dev-tool light, single cobalt anchor · `hum` — playful multi-accent
+consumer warmth · `lumen` — premium AI-apparatus dark (atmospheric
+blooms). A completed design-DNA study SUSPENDS the catalog — the studied
+DNA is the system (`design-system/references/design-dna-study.md`).
+
+## 11. Canonical Reflex-Reject (fonts + aesthetic lanes)
+
+> Derived from [impeccable](https://github.com/pbakaus/impeccable)
+> (Apache-2.0) and [hallmark](https://github.com/nutlope/hallmark) (MIT) —
+> license texts at `departments/brand/skills/design-review/references/`.
+> This section is the SINGLE canonical home of the list. Skills and gates
+> point here; they never restate it (drift risk).
+
+These are **training-data defaults**: every LLM reaches for them by
+reflex, which is exactly why using them by reflex produces monoculture.
+The semantics are **never-by-reflex**, not never:
+
+1. **Identity-preservation carve-out** — when the existing brand has
+   already committed to a font or lane, identity wins. The list governs
+   greenfield decisions only.
+2. **Deliberate-pick carve-out** — a listed font may be used when a named
+   theme or brief *deliberately* selects it and the choice is stated with
+   its reason (e.g. Playfair Display as display-only in an editorial
+   theme; Space Grotesk in a brutalist direction). Reflex is the crime,
+   not the font.
+3. **Product-register carve-out** — product UI (design SERVES the task)
+   has explicit permission for system fonts and familiar sans defaults
+   (Inter, SF Pro, system-ui). The ban list bites on BRAND surfaces
+   (design IS the product). See
+   `departments/brand/skills/design-review/references/design-registers.md`.
+
+### Reflex-reject fonts
+
+**Sans:** Inter · DM Sans · Space Grotesk · Outfit · Plus Jakarta Sans ·
+Instrument Sans · Syne · Roboto · Open Sans · Lato · Poppins · Source Sans ·
+Nunito · Montserrat · Raleway · Work Sans · system-ui-as-brand · Arial ·
+Helvetica-as-default
+**Serif:** Fraunces · Newsreader · Lora · Crimson / Crimson Pro / Crimson
+Text · Playfair Display · Cormorant / Cormorant Garamond · DM Serif Display ·
+DM Serif Text · Instrument Serif · Merriweather · Source Serif ·
+Georgia-as-default
+**Mono:** IBM Plex Mono · Space Mono · Courier New · Consolas-as-default ·
+system-mono-as-brand
+**Family-wide:** IBM Plex Sans · IBM Plex Serif
+
+Selection discipline when rejecting a reflex pick: run the 4-step
+physical-object font procedure in `design-registers.md` (three concrete
+brand-voice words → reject reflex picks → browse a real catalog for the
+brand as a physical object → cross-check).
+
+### Reflex-reject aesthetic lanes
+
+- **Editorial-typographic** — display serif (often italic) + small mono
+  labels + ruled separators + monochromatic restraint. The 2026 fingerprint:
+  three rule-separated columns, an italic serif headline, lowercase
+  track-spaced metadata, no imagery. Every Stripe-adjacent and
+  Notion-adjacent brand has landed here. Requires a register reason that
+  *demands* it (a literal magazine), not a mood.
+
+Lanes saturate and desaturate over time — entries move in and out on
+evidence, mirroring upstream. The **second-order slop check** applies: if
+the aesthetic family is guessable from category-plus-anti-references
+("fintech that's not navy-and-gold → terminal-native dark mode"), it is
+the trap one tier deeper. Rework until neither the first-order nor the
+second-order answer is obvious.
+
+## 12. Design Laws (hard floors and ceilings)
+
+> Derived from [impeccable](https://github.com/pbakaus/impeccable)
+> (Apache-2.0) and [hallmark](https://github.com/nutlope/hallmark) (MIT).
+> Compact canonical table — one law per line. The enforcement surfaces
+> (slop gates, design-slop detector, QG visual review) cite these; deeper
+> rationale lives in `design-review/references/`.
+
+**Typography**
+- Body contrast ≥ 4.5:1; large text (≥18px, or bold ≥14px) ≥ 3:1;
+  placeholders need 4.5:1 too — muted-gray-on-tinted-near-white is the
+  single biggest readability failure.
+- Prose line length 65–75ch (dense data UI may run denser).
+- Hero/display ceiling: `clamp()` max ≤ 6rem. Above that the page shouts.
+- Display letter-spacing floor ≥ −0.04em — tighter and letters touch.
+- `text-wrap: balance` on h1–h3; `text-wrap: pretty` on long prose.
+- Max 3 font families per page (display + body + one outlier). Four = slop.
+- Pair on a contrast axis (serif+sans, geometric+humanist) or use one
+  family with committed weight contrast — never two similar sans.
+- Light-on-dark compensation runs on three axes: line-height +0.05–0.1,
+  letter-spacing +0.01–0.02em, optionally body weight one notch up.
+- Commit to extremes: weight 200 next to 800 reads as intentional;
+  400 next to 600 reads as a default setting.
+
+**Color**
+- OKLCH for new palettes. Pure gray is dead: tint neutrals 0.005–0.015
+  chroma toward the brand hue (never default-tint warm/cool).
+- The warm-neutral band (L 0.84–0.97, C < 0.06, hue 40–100) is the
+  saturated AI default — cream/sand/paper by any token name
+  (`--paper`, `--cream`, `--sand`, `--linen`, `--parchment`…) is a tell.
+  Warmth is carried by accent + typography + imagery, not body bg.
+- Pick a color strategy BEFORE colors, on the commitment axis:
+  **Restrained** (neutrals + one accent ≤10%) · **Committed** (one
+  saturated color, 30–60% of surface) · **Full palette** (3–4 named
+  roles) · **Drenched** (the surface IS the color).
+- Gray text on colored backgrounds washes out: use a darker shade of the
+  background's own hue or a transparency of the text color.
+- Button text vs fill must differ by > 5% lightness or > 0.05 chroma in
+  OKLCH (catches the black-on-black bug).
+- Heavy alpha/transparency is a design smell — it usually means an
+  incomplete palette.
+
+**Layout**
+- Nested cards are always wrong; cards only when truly the best affordance.
+- Flexbox for 1D, Grid for 2D; breakpoint-free grids via
+  `repeat(auto-fit, minmax(280px, 1fr))`.
+- Semantic z-index scale (dropdown → sticky → modal-backdrop → modal →
+  toast → tooltip); never 999/9999.
+- Vary spacing for rhythm: generous separations, tight groupings —
+  monotonous spacing is a tell.
+- Touch targets ≥ 44×44 (extend hit area via `::before { inset: -10px }`
+  when the visual must stay smaller).
+
+**Motion**
+- Ease out with exponential curves (ease-out-quart/quint/expo); no bounce,
+  no elastic, no browser-default `ease`.
+- Exits run ~75% of the enter duration.
+- `prefers-reduced-motion` alternative is mandatory for every animation.
+- Never animate CSS layout properties without real need; motion conveys
+  state on product surfaces, never decoration.
+- The uniform fade-and-rise reveal on every scrolled section is a tell —
+  each reveal fits what it reveals; zero motion is not the fix either.
+- Reveal animations enhance an already-visible default — never gate
+  content visibility on a class-triggered transition (ships blank in
+  hidden tabs and headless renderers).
+
+**Interaction**
+- Every interactive element ships all 8 states: default, hover,
+  focus-visible, active, disabled, loading, error, success. Missing any =
+  unfinished.
+- Skeletons for loading, not spinners in content; empty states teach the
+  interface.
+- Modal as first thought is laziness — exhaust inline/progressive
+  alternatives first.
+
+**Absolute bans (match-and-refuse — rewrite the element, never ship):**
+side-stripe borders (`border-left/right` > 1px as accent) · gradient text
+(`background-clip: text`) · glassmorphism-as-default · the hero-metric
+template (big number + small label + gradient accent) · identical
+icon+heading+text card grids · tiny uppercase tracked eyebrow above every
+section · numbered section markers (01/02/03) as default scaffolding ·
+text overflowing its container at any breakpoint.
+
+These laws are floors, not aspirations: §8's three default looks plus any
+absolute-ban hit are constitution violations under `excellence-mandate`.

package/departments/brand/skills/colors/SKILL.md

@@ -9,6 +9,10 @@ description: >
   brand/design-system (tokens, atomic catalog, WCAG gates for the whole UI);
   complete brand identity from strategy up -> brand/identity-system.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+metadata:
+  origin: community
+  source: https://github.com/nutlope/hallmark
+  license: MIT
 ---
 
 <!-- arka:kb-first-prefix begin -->
@@ -79,7 +83,11 @@ the squad reference.
    "blue"): `surface` (canvas), `ink` (text), `primary` (identity),
    `accent` (signal, ≤ 10–15% usage), plus optional `positive`/`danger`
    semantics. Derive tints/shades in OKLCH so lightness steps are
-   perceptually even; give each role a hex.
+   perceptually even; give each role a hex. **The full construction
+   algorithm lives in `references/oklch-theme.md`** (anchor → paper →
+   ink → greys → focus → accent-ink, with L/C bands per vibe, tinted
+   neutrals, dark-mode-is-not-inverted-light, and three worked
+   examples) — follow it, don't improvise the steps.
 4. **WCAG pairs table** — for every text-bearing combination, compute
    the contrast ratio and mark AA/AAA for body and large text. Any pair
    below AA is redesigned, not footnoted.

package/departments/brand/skills/colors/references/hallmark.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hallmark contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.