arkaos 2.49.0 → 2.50.0

package/VERSION

@@ -1 +1 @@
-2.49.0
+2.50.0

package/departments/brand/skills/design-system/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: brand/design-system
 description: >
-  Design system specification: tokens, atoms, molecules, organisms, templates.
+  Production design system specification: tokens, atoms, molecules, organisms,
+  templates, and pages — with WCAG AA conformance and Storybook export contract.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
@@ -21,12 +22,183 @@ does not replace the vault.
 
 # Design System — `/brand design-system`
 
-> **Agent:** Sofia D. (UX Designer) | **Framework:** Atomic Design (Brad Frost) + Design Tokens
+> **Lead:** Sofia D. (UX Designer) + Isabel (Visual Designer) | **Framework:** Atomic Design (Brad Frost) + Design Tokens + WCAG 2.2 AA
 
-## What It Does
+## What ships
 
-Design system specification: tokens, atoms, molecules, organisms, templates.
+A production design system in 5 deliverables:
 
-## Output
+1. **`design-tokens.json`** — semantic token layer
+2. **Component catalog** — atoms → molecules → organisms → templates → pages
+3. **WCAG 2.2 AA conformance report** — pass / waiver per component
+4. **Storybook story stubs** — one story per component, ready to drop into Storybook
+5. **Integration guide** — how to wire the system into a Vue/React/Vanilla project
 
-Design system spec with token definitions, component catalog, and usage guidelines
+## Token JSON schema
+
+The token system has a **two-layer architecture**: raw primitives + semantic aliases. Semantic tokens reference primitives; surfaces reference semantic tokens. Never reference primitives directly in components.
+
+```json
+{
+  "$schema": "https://design-tokens.github.io/community-group/format/",
+  "primitive": {
+    "color": {
+      "neutral": {
+        "0":   { "$value": "#FFFFFF",  "$type": "color" },
+        "50":  { "$value": "#FAFAFA",  "$type": "color" },
+        "100": { "$value": "#F4F4F5",  "$type": "color" },
+        "900": { "$value": "#18181B",  "$type": "color" },
+        "1000":{ "$value": "#0A0A0A",  "$type": "color" }
+      },
+      "accent": {
+        "500": { "$value": "#00FF88",  "$type": "color" }
+      }
+    },
+    "size": {
+      "0": { "$value": "0",    "$type": "dimension" },
+      "1": { "$value": "4px",  "$type": "dimension" },
+      "2": { "$value": "8px",  "$type": "dimension" },
+      "4": { "$value": "16px", "$type": "dimension" }
+    }
+  },
+  "semantic": {
+    "color": {
+      "background": { "$value": "{primitive.color.neutral.1000}", "$type": "color" },
+      "surface":    { "$value": "{primitive.color.neutral.900}",  "$type": "color" },
+      "text":       { "$value": "{primitive.color.neutral.50}",   "$type": "color" },
+      "accent":     { "$value": "{primitive.color.accent.500}",   "$type": "color" }
+    },
+    "space": {
+      "compact":  { "$value": "{primitive.size.2}",  "$type": "dimension" },
+      "default":  { "$value": "{primitive.size.4}",  "$type": "dimension" },
+      "generous": { "$value": "{primitive.size.6}",  "$type": "dimension" }
+    },
+    "radius": { "$value": "{primitive.size.2}", "$type": "dimension" },
+    "motion": {
+      "duration": {
+        "fast":   { "$value": "150ms",  "$type": "duration" },
+        "base":   { "$value": "250ms",  "$type": "duration" },
+        "slow":   { "$value": "400ms",  "$type": "duration" }
+      },
+      "easing": {
+        "standard": { "$value": "cubic-bezier(0.4, 0, 0.2, 1)", "$type": "cubicBezier" }
+      }
+    }
+  }
+}
+```
+
+Required token groups: `color`, `space`, `typography`, `radius`, `elevation`, `motion`, `border`. Each group must have at minimum 3 semantic tokens. Primitives are reusable; semantics are intentional.
+
+## Atomic Design 5-Level Component Manifest
+
+Each component is documented with: name, level, props, slots, accessibility notes, Storybook story stub.
+
+### Level 1 — Atoms (10-15 required)
+Indivisible UI primitives. Examples:
+
+| Component | Props | A11y notes |
+|---|---|---|
+| Button | `variant` (primary/secondary/ghost), `size`, `disabled`, `loading` | role=button, aria-busy on loading, keyboard-actionable |
+| Input | `type`, `value`, `placeholder`, `disabled`, `invalid` | aria-invalid on invalid, aria-describedby for error |
+| Label | `htmlFor`, `required` | explicit for association required |
+| Icon | `name`, `size`, `decorative` | role=img + aria-label OR aria-hidden when decorative |
+| Avatar | `src`, `alt`, `fallback`, `size` | alt required unless decorative |
+| Badge | `variant`, `count` | aria-live polite when count changes |
+| Spinner | `size`, `label` | role=status + aria-label |
+| Switch | `checked`, `disabled` | role=switch + aria-checked |
+| Checkbox | `checked`, `indeterminate`, `disabled` | aria-checked tri-state support |
+| Link | `href`, `external`, `variant` | rel=noopener for external |
+
+### Level 2 — Molecules (8-12 required)
+Composed pairs of atoms with one task focus. Examples:
+
+| Component | Composes | A11y notes |
+|---|---|---|
+| FormField | Label + Input + ErrorMessage | aria-describedby chain |
+| SearchBar | Input + Button + Icon | role=search, aria-label on form |
+| Card | Heading + Body + optional Footer | semantic landmark when standalone |
+| NavItem | Icon + Label + (Badge) | aria-current when active |
+| Tab | Label + (Icon) + (Badge) | role=tab, aria-selected |
+| Toast | Icon + Body + DismissButton | role=status or alert, dismissible |
+| Tooltip | Anchor + Content | aria-describedby on anchor |
+| Breadcrumb | Link[] + separator | nav landmark, aria-current on last |
+
+### Level 3 — Organisms (6-10 required)
+Complete sections of UI. Examples:
+
+| Component | Composes | A11y notes |
+|---|---|---|
+| NavBar | Logo + NavItem[] + Avatar | nav landmark, skip-link target |
+| HeroSection | Heading + Body + CTA + (Media) | one h1 per page rule |
+| CardGrid | Card[] with layout | role=list when semantic, gap-aware |
+| Dialog | Header + Body + Footer + FocusTrap | role=dialog, aria-labelledby, focus trap |
+| DataTable | Header + Row[] with sort/filter | proper th scope, aria-sort |
+| Sidebar | NavItem[] + collapse | nav landmark, persisted state |
+| EmptyState | Icon + Heading + Body + (CTA) | role=region |
+
+### Level 4 — Templates (3-5 required)
+Page-level layouts with content slots. Examples: DashboardTemplate, ContentTemplate, MarketingTemplate, AuthTemplate, SettingsTemplate.
+
+### Level 5 — Pages (2-3 required, production examples)
+Production-ready pages with real content. Examples: LandingPage, DashboardHome, SettingsAccount.
+
+## WCAG 2.2 AA Gates
+
+Every component must pass:
+
+| Criterion | Check | Tool |
+|---|---|---|
+| 1.4.3 Contrast (Minimum) | Body text ≥ 4.5:1 against background; large text ≥ 3:1 | manual + axe |
+| 1.4.11 Non-text Contrast | UI components and graphical objects ≥ 3:1 against adjacent colors | manual + axe |
+| 2.1.1 Keyboard | All functionality available via keyboard | manual |
+| 2.4.7 Focus Visible | Visible focus indicator on all interactive elements | manual |
+| 2.5.8 Target Size (Minimum) | Pointer targets ≥ 24×24 CSS pixels | manual |
+| 4.1.2 Name, Role, Value | All UI components expose accessible name and role to AT | axe + screen reader |
+| 4.1.3 Status Messages | Status updates announced without focus change | screen reader |
+
+Components failing any criterion either remediate or document a **permanent waiver** with concrete user-impact rationale. Waivers require Quality Gate approval.
+
+## Storybook Export Contract
+
+Each component must ship one `.stories.{ts,mdx}` file with:
+
+- **Default** story — props at defaults, single state visible
+- **AllVariants** story — every variant prop combination
+- **Interactive** story — controls (Storybook args) exposed for every prop
+- **A11y** story — screen-reader narration sample + keyboard nav sequence
+
+Story stubs use the CSF3 format:
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: { a11y: { test: 'error' } },
+  argTypes: {
+    variant: { control: 'select', options: ['primary', 'secondary', 'ghost'] },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    disabled: { control: 'boolean' },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+export const Default: Story = { args: { variant: 'primary', size: 'md' } };
+export const AllVariants: Story = { /* render all variants in a grid */ };
+```
+
+## Integration Guide (delivery artifact)
+
+A standalone markdown explaining:
+- How to install token files (CSS variables / JSON / Tailwind config)
+- How to import components in Vue / React / Vanilla
+- How to extend the system (adding tokens, adding components, namespacing)
+- How to run the WCAG audit locally (`npx axe-core --tags wcag2aa`)
+- How to update Storybook stories when components change
+
+## Output → Obsidian: `WizardingCode/Brand/DesignSystems/<project>-<date>/`
+
+Delivers: `design-tokens.json` + component catalog (markdown with screenshots / mermaid hierarchy) + WCAG report + Storybook stubs + integration guide.

package/departments/brand/skills/primal-audit/SKILL.md

@@ -40,12 +40,51 @@ does not replace the vault.
 
 1. **Gather** — Collect all brand assets: website, social, packaging, internal docs
 2. **Map** — Fill each of the 7 elements with what currently exists
-3. **Score** — Rate each element: Strong (3), Present (2), Weak (1), Missing (0)
-4. **Gaps** — Identify missing or weak elements
-5. **Recommend** — Specific actions to strengthen each weak element
-6. **Benchmark** — Compare against competitors' Primal Codes
+3. **Score** — Apply the per-element rubric below (3 points each across 7 elements = 21 total)
+4. **Gaps** — Identify weak elements and the specific sub-criterion that failed
+5. **Recommend** — Specific remediation per gap, ranked by leverage
+6. **Benchmark** — Compare against 3-5 competitors' Primal Codes
 
-## Scoring
+## Per-Element Scoring Rubric (3 sub-criteria each)
+
+Each element is scored 0-3. Mark each sub-criterion present (1) or absent (0); sum to the element score.
+
+### 1. Creation Story (max 3)
+- [ ] **Origin moment is named** — a specific event, year, person, or pain point that triggered the brand
+- [ ] **Consistency across surfaces** — the same story appears on About page, founder bio, key talks
+- [ ] **Emotional anchor present** — a stakes-laden tension the founder needed to resolve
+
+### 2. Creed (max 3)
+- [ ] **Belief is stated, not implied** — explicit "we believe…" or "we exist because…" sentence
+- [ ] **Belief has a counter-position** — the creed names what it rejects, not just what it affirms
+- [ ] **Belief shapes product decisions** — at least one shipped feature can be traced to the creed
+
+### 3. Icons (max 3)
+- [ ] **Symbol is consistent** — same logo / mark across all primary surfaces
+- [ ] **Symbol carries meaning** — the mark is decoded by users (Apple = bite, Nike = motion)
+- [ ] **Sub-icons reinforce** — secondary visual language (palette, type, photography style) supports the primary symbol
+
+### 4. Rituals (max 3)
+- [ ] **Repeated user action defines the brand** — unboxing, onboarding, daily check-in, signature gesture
+- [ ] **The ritual is named or recognizable** — users can describe the ritual back without prompting
+- [ ] **The ritual is protected** — the brand resists altering it; the ritual has loadbearing weight
+
+### 5. Non-Adherents (max 3)
+- [ ] **Opposition is named** — competitors, mindsets, or status-quo positions explicitly called out
+- [ ] **Identity is sharpened by contrast** — what the brand REFUSES is as clear as what it offers
+- [ ] **Tribal lines are visible to outsiders** — adopting the brand signals belonging in a recognizable in-group
+
+### 6. Sacred Lexicon (max 3)
+- [ ] **3+ proprietary terms in active use** — words coined or claimed by the brand that customers repeat
+- [ ] **Vocabulary is taught** — onboarding, docs, or messaging explicitly introduce the lexicon
+- [ ] **Outsiders cannot fake fluency** — using the lexicon correctly signals real adherence
+
+### 7. Leader (max 3)
+- [ ] **A named human embodies the brand** — founder, CEO, public face with personal voice
+- [ ] **Leader carries the creed** — public statements consistently align with the brand's belief
+- [ ] **Leader is accessible** — direct contact channel exists (writing, podcast, social presence, AMAs)
+
+## 21-Point Index
 
 | Score | Rating | Meaning |
 |-------|--------|---------|
@@ -54,4 +93,38 @@ does not replace the vault.
 | 10-13 | Developing | Foundation exists, significant gaps |
 | 0-9 | Underdeveloped | Major brand building needed |
 
+## Evidence Citation Contract
+
+Every per-criterion score MUST cite specific asset evidence. Format:
+
+```
+Creation Story (2/3)
+  ✓ Origin moment named — "Founded 2018 in a coffee shop after the third
+    failed deploy" (About page, 2nd paragraph)
+  ✓ Consistency across surfaces — same story on About + founder LinkedIn
+    + S2 podcast appearance
+  ✗ Emotional anchor present — origin reads as biography, no stakes-laden
+    tension. Suggested remediation: rewrite to surface the cost of the
+    problem (what was at risk if this didn't exist).
+```
+
+A score without evidence is a score without weight. Self-critique phase rejects any unjustified marks.
+
+## Competitor Benchmark Template
+
+For each of 3-5 competitors, complete the same 21-point rubric and compute relative position:
+
+```
+| Brand | Creation | Creed | Icons | Rituals | Non-Adherents | Lexicon | Leader | Total |
+|-------|----------|-------|-------|---------|---------------|---------|--------|-------|
+| Ours  |   2      |   3   |   2   |   1     |   0           |   2     |   3    | 13/21 |
+| CompA |   3      |   3   |   3   |   3     |   2           |   3     |   2    | 19/21 |
+| CompB |   1      |   2   |   2   |   1     |   1           |   1     |   1    |  9/21 |
+| CompC |   2      |   2   |   3   |   2     |   2           |   2     |   1    | 14/21 |
+```
+
+Output **strategic gaps** (where we trail the leader) vs **deliberate non-positions** (where we choose not to compete). Mark each gap with leverage rating: high / medium / low — to be ranked into the remediation plan.
+
 ## Output → Obsidian: `WizardingCode/Brand/Audits/PRIMAL-AUDIT-<brand>-<date>.md`
+
+Includes: per-element scoring with citations, 21-point index, competitor benchmark, ranked remediation plan with leverage ratings, and concrete next-7-days actions for the top 3 gaps.

package/departments/brand/workflows/audit.yaml

@@ -0,0 +1,118 @@
+id: brand-audit
+name: Brand Audit
+description: Diagnose an existing brand against the 7 Primal Code elements with competitor benchmark
+department: brand
+tier: enterprise
+command: "/brand audit"
+requires_branch: false
+requires_spec: false
+quality_gate_required: true
+
+phases:
+  - id: brief
+    name: Audit Brief
+    description: Define brand under audit, audience, competitors to benchmark against
+    agents:
+      - agent_id: brand-director-valentina
+        role: Frame audit scope, identify the 3-5 competitor brands for benchmark
+    gate:
+      type: user_approval
+      description: User confirms brand-under-audit and competitor set
+
+  - id: asset-gather
+    name: Asset Gathering
+    description: Collect all live brand assets (logo, palette, type, voice samples, taglines, web/social proof points)
+    agents:
+      - agent_id: brand-director-valentina
+        role: Catalog the brand surface area, flag missing assets
+      - agent_id: visual-designer-isabel
+        role: Extract visual tokens from existing materials
+        parallel: true
+    gate:
+      type: auto
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Brand/Audits/Assets/"
+        description: Asset inventory with file references
+
+  - id: seven-element-mapping
+    name: Primal 7-Element Mapping
+    description: Score each Primal element (Creation Story, Creed, Icons, Rituals, Sacred Words, Non-Believers, Leader) against evidence
+    agents:
+      - agent_id: brand-strategist-mateus
+        role: Score Creation Story, Creed, Sacred Words, Non-Believers, Leader against asset evidence
+        parallel: true
+      - agent_id: ux-designer-sofia-d
+        role: Score Icons and Rituals against UI/interaction evidence
+        parallel: true
+    gate:
+      type: auto
+
+  - id: scoring
+    name: 21-Point Scoring
+    description: Aggregate per-element scores into a 21-point Primal Code Index (3 points per element across 7 elements)
+    agents:
+      - agent_id: brand-strategist-mateus
+        role: Compute the 21-point Primal Code Index, identify gaps
+    gate:
+      type: user_approval
+      description: User reviews the 21-point scoring before benchmark phase
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Brand/Audits/Scoring/"
+        description: 21-point Primal Code Index with per-element evidence
+
+  - id: competitor-benchmark
+    name: Competitor Benchmark
+    description: Run the same 21-point scoring on 3-5 competitor brands; compute relative position
+    agents:
+      - agent_id: brand-strategist-mateus
+        role: Benchmark competitor scores, compute relative position
+      - agent_id: strategy-director-tomas
+        role: Strategic context — which gaps are wins to close, which are deliberate non-positions
+        parallel: true
+    gate:
+      type: user_approval
+      description: User approves the benchmark results before remediation ranking
+
+  - id: self-critique
+    name: Self-Critique
+    description: Stress-test the audit — are scores defensible by evidence? Are gaps actionable?
+    agents:
+      - agent_id: brand-director-valentina
+        role: Verify each score has a concrete asset citation, each gap has a measurable target
+    gate:
+      type: auto
+
+  - id: quality-gate
+    name: Quality Gate
+    model_override: opus
+    description: Mandatory quality review
+    agents:
+      - agent_id: cqo-marta
+        role: Orchestrate quality review
+      - agent_id: copy-director-eduardo
+        role: Audit prose quality, no clichés, defensible scoring language
+        parallel: true
+      - agent_id: tech-director-francisca
+        role: Visual evidence completeness, accessibility findings, file format integrity
+        parallel: true
+    gate:
+      type: quality_gate
+      required_verdict: APPROVED
+
+  - id: delivery
+    name: Audit Report & Recommendations
+    description: Compile audit report with ranked remediation recommendations
+    agents:
+      - agent_id: brand-director-valentina
+        role: Compile audit report — 21-point index, gap analysis, ranked remediation plan
+    gate:
+      type: auto
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Brand/Audits/"
+        description: Complete brand audit with 21-point index + competitor benchmark + ranked recommendations

package/departments/brand/workflows/design-system.yaml

@@ -0,0 +1,122 @@
+id: brand-design-system
+name: Design System Specification
+description: Production design system from tokens to Storybook components (Atomic Design + WCAG AA)
+department: brand
+tier: enterprise
+command: "/brand design-system"
+requires_branch: false
+requires_spec: false
+quality_gate_required: true
+
+phases:
+  - id: brief
+    name: Design System Brief
+    description: Define product surface, platforms, accessibility floor, integration target
+    agents:
+      - agent_id: brand-director-valentina
+        role: Frame system scope (web / mobile / multi-product), confirm accessibility floor (WCAG AA minimum)
+    gate:
+      type: user_approval
+      description: User confirms scope, platforms, and accessibility floor
+
+  - id: token-design
+    name: Token Design
+    description: Define design tokens (color, typography, spacing, radius, elevation, motion) as JSON
+    agents:
+      - agent_id: visual-designer-isabel
+        role: Color palette with semantic tokens, typography scale, spacing rhythm, radius/elevation/motion tokens
+    gate:
+      type: user_approval
+      description: User approves the token system before component build
+    outputs:
+      - type: document
+        format: json
+        obsidian_path: "WizardingCode/Brand/DesignSystems/Tokens/"
+        description: design-tokens.json with full semantic layer
+
+  - id: atom-molecule-organism
+    name: Atom, Molecule, Organism
+    description: Build the lower three Atomic Design levels — primitives, composed pairs, complete sections
+    agents:
+      - agent_id: ux-designer-sofia-d
+        role: Atoms (button, input, label, icon), molecules (form field, card header, nav item)
+        parallel: true
+      - agent_id: visual-designer-isabel
+        role: Organisms (nav bar, hero, card grid, dialog) with token application
+        parallel: true
+    gate:
+      type: auto
+
+  - id: template-page
+    name: Templates & Pages
+    description: Complete Atomic Design — page templates with content placeholders, plus 2-3 production page examples
+    agents:
+      - agent_id: ux-designer-sofia-d
+        role: Page templates (landing, dashboard, settings, empty state)
+      - agent_id: visual-designer-isabel
+        role: Production page examples with real content
+        parallel: true
+    gate:
+      type: user_approval
+      description: User approves the template set before accessibility audit
+
+  - id: accessibility-audit
+    name: WCAG AA Audit
+    description: Full WCAG 2.2 AA audit on every component — contrast, focus, semantics, ARIA, keyboard
+    agents:
+      - agent_id: wcag-auditor
+        role: WCAG 2.2 AA conformance audit on every atom/molecule/organism/template
+      - agent_id: ux-designer-sofia-d
+        role: Remediate failures, document permanent waivers with rationale
+        parallel: true
+    gate:
+      type: user_approval
+      description: User approves the conformance report (zero AA failures required)
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Brand/DesignSystems/Accessibility/"
+        description: WCAG AA conformance report — every component pass/waiver
+
+  - id: self-critique
+    name: Self-Critique
+    description: Stress-test the system — naming consistency, token coverage, scale integrity, edge-case components
+    agents:
+      - agent_id: brand-director-valentina
+        role: Verify naming consistency, token coverage, scale integrity, edge-case components
+    gate:
+      type: auto
+
+  - id: quality-gate
+    name: Quality Gate
+    model_override: opus
+    description: Mandatory quality review
+    agents:
+      - agent_id: cqo-marta
+        role: Orchestrate quality review
+      - agent_id: copy-director-eduardo
+        role: Component naming, prop names, docstring clarity, no AI clichés in copy
+        parallel: true
+      - agent_id: tech-director-francisca
+        role: Token schema integrity, accessibility compliance, Storybook contract correctness
+        parallel: true
+    gate:
+      type: quality_gate
+      required_verdict: APPROVED
+
+  - id: delivery
+    name: Design System Delivery
+    description: Compile the design system — tokens JSON + component catalog + WCAG report + Storybook story stubs
+    agents:
+      - agent_id: brand-director-valentina
+        role: Compile the design system package and write the integration guide
+      - agent_id: shadcn-padronizer
+        role: Optional shadcn/ui alignment for code-side parity
+        optional: true
+    gate:
+      type: auto
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Brand/DesignSystems/"
+        description: Complete design system — design-tokens.json + component catalog + accessibility report + Storybook stubs + integration guide

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.49.0",
+  "version": "2.50.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.49.0"
+version = "2.50.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}