Skip to content

AGENT-CONTEXT.md

Latest commit

 

History

History
132 lines (96 loc) · 4.07 KB

AGENT-CONTEXT.md

File metadata and controls

132 lines (96 loc) · 4.07 KB
Raw

Underlith — Session Context

Underlith — open-source governance layer for design tokens.

Core Positioning (FINAL)

  • Hero: "Your brand is a contract. Underlith enforces it."
  • Subtitle: "Governable design tokens for teams building across frameworks and platforms."
  • CTA: "Create your source of truth"
  • Key line: "Underlith is not your source of truth — it's the infrastructure to build one."

Three distinct trios (do not conflate)

Macro layers (architecture / home / OVERVIEW)

  1. Token Infrastructure
  2. CLI Integration
  3. Governance Tooling

Governance levels (GOVERNANCE.md)

  • Level 1 — Underlith core (@mikaelcarrara/underlith) — primitives, slow, stable
  • Level 2 — @your-org/tokens — brand contract, your cadence
  • Level 3 — Product consumers — web, mobile, admin, AI agent

Token types

  1. Primitives
  2. Semantic
  3. Brand

Token rules (canonical)

  • Naming: --ul-{category}-{intent} canonical, --ul-color-{intent} alias
  • Single consumption path: var(--ul-color-*) only — no literals anywhere
  • Alias mapping lives in globals.css only — never in components
  • @your-org/tokens is the only import products need
  • underlith.base.css / underlith.brand.css — Underlith core (Level 1)
  • your-org.base.css / your-org.brand.css — generated by brand init (Level 2)

CLI flows

# New project
underlith brand init --org your-npm-username

# Existing shadcn project
underlith init --shadcn --globals ./styles/globals.css

# Roadmap
underlith migrate   # AI-assisted literal → token replacement
underlith audit     # token adoption coverage report

CI jobs (canonical)

  • build:tokens
  • lint:tokens
  • lint:tokens-check — detects hardcoded literals in components
  • breaking-change detection
  • test:contrast — WCAG AA for status and brand tokens
  • visual-regression (recommended)
  • audit-log

Status tokens

--ul-status-success:    oklch(0.30 0.13 145);
--ul-status-success-bg: oklch(0.98 0.03 145);
--ul-status-warning:    oklch(0.40 0.12 75);
--ul-status-warning-bg: oklch(0.97 0.04 75);
--ul-status-error:      oklch(0.40 0.16 25);
--ul-status-error-bg:   oklch(0.97 0.04 25);
--ul-status-info:       oklch(0.40 0.13 240);
--ul-status-info-bg:    oklch(0.97 0.04 240);

Files produced (outputs)

File Status
ai-agents.html ✓ updated
OVERVIEW.md ✓ three main layers, Observability moved to roadmap
GOVERNANCE.md ✓ three levels, token drift, agent-readiness, CI table
README.md ✓ usage examples show @your-org/tokens, not underlith direct
.cursorrules ✓ governance-only, for users to drop in their project
agent-thinking.html ✓ animated agent thinking UI for AI & Agents section
governance.html ✓ aligned with GOVERNANCE.md

agent-thinking.html

Animated component simulating an AI agent operating within token governance rules.

  • Vertical line with traveling dot (JS-controlled, stops at last item)
  • Four groups: resolve → validate → drift → output
  • Each group ends with a dry observational summary line
  • Color rules: --ul-* token names in lime, var( in white, .tsx files near-white, status column colored
  • Metaphor: what a .cursorrules with Underlith governance rules does in practice
  • Intended for the ai-agents.html page, section "Token governance for AI-generated UI"

Pending

  • Integrate agent-thinking.html into ai-agents.html section
  • Commit all docs to main repo
  • Rafael to merge Kobana PR and publish @kobana/tokens
  • underlith migrate — roadmap implementation

Roadmap (site nav)

  • Q3 2026 — Automation (linter, pre-commit hooks, CI templates, underlith audit)
  • Q4 2026 — Ecosystem (underlith migrate, TypeScript types, visual regression, MCP server, Figma sync)
  • Future — Control Plane (project registry, token version tracking, dependency graphs)