CodaMetrix design system

CodaMetrix Design System

The CodaMetrix design system is the single authoritative source for visual and interaction standards across all CodaMetrix brand touchpoints — marketing, product, social, and print.

---

Three Forms

The system ships in three coordinated forms. They are maintained in sync; the token canon is the root.

(a) Markdown token canon — this folder

The source of truth lives here on Drive. Every foundation doc, component spec, media guideline, and token file is authored and updated in this folder tree. When in doubt, this is the reference.

(b) GSAP living styleguide — DS/styleguide/

A browser-rendered styleguide built with GSAP. It renders Code Block animations, Pixel Wave behaviors, typography specimens, and color swatches live against actual token values. Run it locally or deploy it for review. The styleguide is generated from the tokens — do not hard-code values in styleguide source files.

(c) React component package — PreHealth-inc/codametrix-ds (off-Drive git repo)

The npm-installable React component library. Components are the production-ready implementation of every spec in 10-components/. The package is versioned and published separately from this Drive folder.

---

Tier Map

Design System/
├── 00-foundations/     Color, typography, logo, code blocks, pixel waves,
│                       photography, iconography, motion, space & grid
├── 10-components/      13 reusable UI and layout components
├── 20-media/           Social, digital, print, and video/motion specs
├── tokens/
│   ├── tokens.json     ← Single source of truth for all design tokens
│   ├── tokens.css      ← Generated output; do NOT hand-edit
│   └── print-cmyk.md   Print CMYK reference
└── styleguide/         GSAP living styleguide (generated)

Foundation docs define the laws of the visual system — geometry, color, type, motion. Component docs apply those laws to specific UI patterns. Media docs translate the system to production formats. Tokens are the numeric bridge between the markdown canon and every code artifact.

---

Contribution Rule

This contribution rule is mandatory for all token changes. > The single source of truth is tokens/tokens.json. To change any design token, you must follow this propagation chain — never shortcut it.

1. Edit tokens/tokens.json — change only in this file. Do not edit tokens.css directly; it is a generated artifact and any hand-edits will be overwritten.
2. Run build-tokens.mjs — execute the build script to regenerate both tokens/tokens.css AND re-emit the presocial brand-spec (written to Social/Rubric/social-rubric.md): node build-tokens.mjs tokens/tokens.json tokens/tokens.css /tmp/codametrix-brand-spec.txt
3. Rebuild the React package — in the PreHealth-inc/codametrix-ds repo, run npm run build to pick up the new token values in the component library.
4. Reload the styleguide — rebuild or refresh the GSAP styleguide so rendered specimens reflect the new values.

One source, propagated outward. If a value appears in tokens.css, the styleguide, the React package, and social-rubric.md but not in tokens.json, something has drifted — treat it as a bug and fix tokens.json as the root.

---

Ship / No-Ship Gate

All assets produced from this design system must pass the scoring rubric before shipping externally. See ../Brand Instructions/brand-rubric.md for the full rubric.

The 4 hard-fail gates — any one is an automatic Do Not Ship, regardless of overall score:

1. AI-replaces-people framing. Any asset that frames CodaMetrix as replacing coders, reducing headcount, or "taking jobs" must not ship. (violates brand + soul)
2. Wrong logo or mark. Using a flowing ribbon, loop, or infinity shape in place of the angular interlocking-links icon; or any distorted, shadowed, or recolored logo version. (violates brand-style-guide §logo)
3. Off-palette colors used as brand colors. Any color not drawn from tokens/tokens.json §primitive used in a brand-color role. (violates brand-style-guide §color-palette)
4. Unproven stat claim. Any factual or numeric claim with no source, citation, or documented basis. (violates voice "prove everything")

---

Related

• ../Brand Instructions/brand-rubric.md — ship/no-ship scoring rubric
• ../Brand Instructions/brand-style-guide.md — visual standards source
• ../Brand Instructions/voice.md — written voice standards
• design-system.md — full table of contents for all DS docs

CodaMetrix Design System — Table of Contents

Complete index of every document in the design system. All links are relative to this file.

---

Foundations

Core laws of the visual system. No component or media spec may contradict a foundation doc.

• Color — primitives, semantic tokens, signature gradient, dual-coral rule, contrast pairings
• Typography — three typefaces, six-step hierarchy, leading and tracking tokens
• Logo — approved versions, clearance rules, the interlocking-links mark, never-do list
• Code Blocks — geometry law, four roles, color fills, implementation recipe
• Pixel Waves — Wave 1 (bold/hero) and Wave 2 (stepped/footer), shared rules
• Photography — subject matter, mood, lighting, in-Code-Block masking rules
• Iconography — style, stroke weight, sizing tokens, corner treatment
• Motion — duration tokens, easing tokens, six motion principles
• Space & Grid — spacing scale, 12-column grid, breakpoints, social safe areas

---

Components

Reusable UI and layout components. Each spec references the foundation tokens it depends on and declares its hard-fail gates.

• Award & Event Chip
• Bulleted Proof
• Code Block Primitive
• Content Container
• CTA Pill
• Headline + Coral Rule
• Image Mask Block
• Logo Lockups
• Pixel Wave Primitive
• Proof Point List
• Quote Card
• Section Tag
• Stat Block

---

Media

Production specifications for each output format. Apply foundation + component standards to real-world format constraints.

• Social — Instagram, LinkedIn; safe areas, carousel layout DNA, platform-specific rules
• Digital — web, email, display advertising
• Print — paper specs, bleed, safe area, CMYK production
• Video & Motion — frame rates, export specs, motion principle application

---

Tokens

Design token files. tokens.json is the single source of truth; tokens.css is generated output.

• tokens.json — source of truth — all primitive and semantic token values; edit here only
• tokens.css — generated CSS custom properties; do NOT hand-edit
• print-cmyk.md — CMYK equivalents for print production

---

Styleguide

The GSAP living styleguide renders token values, component specimens, and animation behaviors in the browser.

• styleguide/ — local or hosted GSAP styleguide; rebuild after any token change (see README.md §Contribution Rule)

Compiled package — pointer

The React/TypeScript token + component package (codametrix-ds) is NOT vendored here.

• Engineering source of truth: the codametrix-ds git repo (local dev clone: /Users/cleverish/dev/codametrix-ds). src/tokens.json there is the upstream of tokens/tokens.json in this folder (byte-identical at sync time; tokens.css is built from it via npm run build).
• Built mirror (with node_modules/dist): the Drive vault copy at __PreWiki/Clients/Codametrix/Design System/package/ (design-sync clone; too heavy for this repo).

Rule: change tokens in codametrix-ds/src/tokens.json first, rebuild, then re-sync this folder's tokens/ — never edit tokens/tokens.json here by hand.