Axiom

DESIGN is the visual authoring surface for fleet composition. Penpot provides rapid page layout and component design. _TOKENS.scss remains the source of truth. The visual tool is INPUT, governed, validated, and ledgered. No ungoverned pixels reach production.

Constraints

MUST:     Use _TOKENS.scss as single source of truth for all design tokens
MUST:     Diff-gate every Penpot export against _TOKENS.scss (zero drift or fail)
MUST:     Mirror all Liquid section components (26) and SVG figure components (17) as Penpot library
MUST:     Validate WCAG contrast in diff gate (automated accessibility audit)
MUST:     Self-host Penpot (Docker Compose, pinned version, MPL-2.0)
MUST:     Ledger every token update (DESIGN:TOKEN_UPDATE on LEDGER)
MUST NOT: Allow token drift between Penpot and _TOKENS.scss
MUST NOT: Use proprietary design tools (Figma, Sketch, Adobe XD)
MUST NOT: Deploy without magic validate → 255
MUST NOT: Edit compiled CSS directly (fix tokens or Penpot source)

COVERAGE: 255/255

SPEC

Purpose

DESIGN is the visual authoring surface for fleet composition. Penpot (open-source, self-hosted, SVG/CSS-native, MCP-enabled) provides rapid page layout and component design. _TOKENS.scss remains the source of truth. The visual tool is INPUT — governed, validated, and ledgered.

DESIGN bridges the gap between code-first governance and visual design velocity. Developers and governors compose fleet pages visually — HERO + CARDS + DASHBOARD + CTA — then the governance pipeline validates tokens, enforces constraints, and deploys. No ungoverned pixels reach production.

Structure

Leaf SERVICE scope. No governed child scopes.

Consumes:

• _TOKENS.scss — 80+ CSS custom properties (color, spacing, typography, motion, glass)
• _includes/*.html — 26 Liquid section components
• _includes/figures/*.html — 17 SVG figure components
• _layouts/*.html — 7 page layouts (default, econ, deck, custom, post, paper, book)
• CANON.json — scope accents, brand marks, system prompts (per fleet site)

Produces:

• Visual composition previews (Penpot files — SVG native)
• Token export diffs (penpot-export → tokens.json → diff gate)
• Component library mirror (26 sections + 17 figures as Penpot components)

Required closure artifacts per scope: CANON.md, README.md, DESIGN.md, VOCAB.md, ROADMAP.md, COVERAGE.md, LEARNING.md, INTEL.md.

Learning lane per governed scope: LEARNING.md at the scope root is terminal and SHALL NOT nest further LEARNING/.

Routes

web_docs:    https://hadleylab.org/
web_surface: https://hadleylab.org/SERVICES/DESIGN/
magic:       magic://hadleylab.org/SERVICES/DESIGN/

Token Pipeline

Penpot (visual authoring — INPUT)
  ↓
penpot-export → tokens.json (CSS / SCSS / JSON)
  ↓
DIFF GATE: tokens.json vs _TOKENS.scss
  ↓ PASS                    ↓ FAIL
_TOKENS.scss unchanged     CI blocks — drift report
  ↓                         ↓
build → DESIGN.css         Fix in Penpot or _TOKENS.scss
  ↓
magic validate → 255
  ↓
Deploy fleet

Component Library

MCP Integration

Claude Agent ↔ MCP Server (:4401) ↔ WebSocket ↔ Penpot Plugin API ↔ Design File

Governed operations via MCP:

• Read: inspect component properties, export tokens, list pages
• Write: update token values, create components, compose layouts
• Validate: check against CANON.md constraints (WCAG, token enforcement)

Ecosystem Connectivity

1. Upstream: SERVICES governance contracts and hadleylab-canonic scope inheritance.
2. Runtime: ~/.canonic/design/ (remote_theme repository — canonic-canonic/DESIGN).
3. Frontend: _TOKENS.scss → DESIGN.css → all fleet surfaces.
4. Ledger plane: DESIGN:TOKEN_UPDATE, DESIGN:COMPONENT_UPDATE events on LEDGER.
5. MCP: Penpot MCP server → Claude agent → design compliance via MAGIC.

Pages

Default: Overview.

INTEL

Penpot Architecture

Data Sources

Token Sync Strategy

Integration Risks

Competitive Analysis

Penpot is the only tool that satisfies all CANONIC governance constraints: open-source, self-hosted, SVG/CSS/HTML native, official MCP server, and zero licensing cost.

LEARNING

Patterns

ROADMAP

Now

• [ ] CANON.md — create proper CANON.md with axiom/inherits header (MAGIC 255 closure, DESIGN.md exists but is not CANON.md)
• [x] DESIGN service governance scaffolded (8 closure artifacts at 255)
• [x] Penpot evaluated as visual authoring surface (open-source, self-hosted, MCP-enabled)
• [x] Token pipeline architecture defined (one-way flow, diff gate, _TOKENS.scss authority)
• [ ] Self-host Penpot instance (Docker Compose, pinned version)
• [ ] Integrate Penpot MCP server with Claude agent config
• [ ] MAMMOCHAT marketing surface — first CANONIC visual port of external site

Next

• Mirror 26 Liquid section components as Penpot library
• Mirror 17 SVG figure components as Penpot library
• Implement penpot-export → diff gate in CI pipeline

Later

• Automated design-drift detection (DESIGN:TOKEN_UPDATE events on LEDGER)
• Cross-principal visual review (all 6 principals' pages in one Penpot project)
• Native app surface tokens (Swift/Kotlin) synced from same _TOKENS.scss authority
• GALAXY visualization as interactive Penpot component

VOCAB

INHERITANCE CHAIN

SERVICES

SERVICES compose primitives — INTEL + CHAT + COIN. Every service governed. Every scope discovered.

MUST:     Maintain TRIAD integrity (CANON.md + VOCAB.md + README.md)
MUST:     Treat SPEC as scope identity (`{SCOPE}` directory), not as a file
MUST:     Every SERVICE scope include ROADMAP.md, COVERAGE.md, LEARNING.md, and `{SCOPE}.md` as governed content surfaces
MUST:     Discover SERVICE scopes from filesystem only (no manual catalog)
MUST:     Keep http:// and magic:// on the same namespace (transport differs, scope path matches)
MUST:     CANON.md = axiom + universal constraints (no service names, no paths, no implementation)
MUST:     README.md = how to run the CANON (nothing else)
MUST:     {SCOPE}.md = SPEC — the interface (purpose, routes, projections, ecosystem)
MUST:     SHOP.md = public projection file (per scope, filesystem-discoverable)
MUST:     VAULT.md = private projection file (per scope, filesystem-discoverable)
MUST:     Runtime implementation remains under ~/.canonic; this workspace is governance-first
MUST NOT: Hardcode service names in CANON constraints (law speaks universals)
MUST NOT: Define ungoverned terms outside VOCAB.md
MUST NOT: Treat `{SCOPE}.md` as SPEC identity
MUST NOT: Move architecture/lifecycle into README
MUST NOT: Leak private projections to public surfaces
MUST NOT: Maintain duplicate mapping tables outside generated manifest outputs
MUST NOT: Add runtime jargon to governance contracts
MUST:     Ledger-consuming services declare source ledgers, scope filters, and closure gates
MUST:     Learning governance remains live — closure claims require fresh DISCOVER → GENERATE → RELINK evidence

hadleylab-canonic

HADLEYLAB ships software. Every app, book, paper, deal, and patent is PROOF that MAGIC works. COIN = WORK. LEARNING = COMPUTE.

MUST:     Every app, book, paper, deal, or patent is evidence of MAGIC
MUST:     All scopes inherit canonic-canonic/CANONIC.md governance
MUST:     All users governed under USERS/ via SERVICES/USER
MUST:     Cross-index INTEL across users (INTEL.md)
MUST:     Shared events propagate to ALL affected user dashboards
MUST:     Maintain governance workspace purity (.md files only)
MUST:     Ledger all COIN (validated work) through MAGIC 255
MUST:     Compile all INTEL from governed sources
MUST:     Keep frontend/runtime implementation under ~/.canonic (hidden runtime)
MUST:     Surface governed TALK, Library, and SERVICES scopes (no orphan content)
MUST:     Derive nav labels from governed scope names (no hardcoded strings)
MUST NOT: Publish without governance (CANON.md required)
MUST NOT: Duplicate primitives — compose from INTEL, CHAT, COIN
MUST NOT: Silo intelligence inside a single user when multiple are affected
MUST NOT: Expose VAULT contents outside NDA scope
MUST NOT: Store runtime artifacts in governance workspace

canonic-canonic

SPEC is governance. `canonic-canonic/` is the spec root.

MUST:     Keep this repo governance-only (.md/.pdf)
MUST:     Publish workspace mapping in CANONIC.git (no hardcoded repo lists)
MUST:     Preserve three primary lanes: FOUNDATION, INDUSTRIES, MAGIC
MUST NOT: Commit runtime artifacts here (runtime belongs in ~/.canonic/)
MUST:     Sell MAGIC tiers — the product, not the proof (proof is hadleylab-canonic)
MUST NOT: Embed beta-test app URLs in platform page content