--- schema: foundry-doc-v1 title: "Design-system substrate" slug: design-system-substrate category: substrate type: topic content_type: topic quality: complete short_description: "The design-system substrate is a self-hosted, customer-owned design-system engine that stores tokens and components in the customer's own Git repository, serves them through a machine-readable MCP endpoint, and uses the W3C DTCG token format to remain editor-agnostic." status: active bcsc_class: public-disclosure-safe last_edited: 2026-05-15 editor: pointsav-engineering cites: - mcp-spec - sigstore-rekor-v2 - c2sp-tlog-tiles - ni-51-102 - osc-sn-51-721 paired_with: design-system-substrate.es.md --- The PointSav design-system substrate is a self-hosted, customer-owned design-system engine. The vendor showcase at `design.pointsav.com` is the canonical instance. Each SMB customer who forks the substrate runs their own instance at their own domain — single codebase, single deployment shape, two contexts. Enterprise-scale managed design systems place tokens, components, and design decisions inside the platform provider's own infrastructure. The customer's theme files live in the vendor's storage; the vendor's continued operation is a dependency for every UI build. Enterprise SaaS tools in this space carry entry pricing that is prohibitive for SMB customers. The substrate inverts that pattern on three structural axes: the customer's design system lives in the customer's Git repository, signed by the customer's key, replayable into any tool; design-decision research lives in the same vault as the tokens and components, served through the same [[mcp-substrate-protocol|Model Context Protocol]] endpoint `[mcp-spec]` that AI agents use; and tokens are stored in the W3C Design Tokens Community Group (DTCG) format, keeping the substrate editor-agnostic by construction. ## Immutable Vault Architecture The substrate's content lives in a per-tenant vault directory: ``` / ├── tokens/ DTCG primitive + semantic + component layers ├── components/ HTML+CSS+ARIA recipe files ├── themes/ per-brand semantic-layer overrides ├── research/ AI-readable design-decision rationale (markdown) └── exports/ derived caches (Figma, Tailwind, Style Dictionary) ``` The vault is the only canonical layer. Rendered exports — Figma Variables JSON, Tailwind config, CSS variables, Style Dictionary builds — are derived caches recomputable from the canonical four directories above. The substrate engine is a stateless HTTP service that reads the vault from disk. Per-tenant isolation is achieved by running one engine process per tenant, each pointed at its own vault. Persistence above the vault filesystem is via the substrate's [[worm-ledger-architecture|WORM ledger]]. Token and component history is anchored monthly to Sigstore Rekor `[sigstore-rekor-v2]`, producing a customer-rooted Merkle log using the C2SP tlog-tiles format `[c2sp-tlog-tiles]`. ## Machine-Readable Context Backplane The `research/` directory is the substrate's most structurally novel element. Every design decision lives as a structured markdown file: ``` --- schema: foundry-design-research-v1 component_or_token: button-primary decision_type: component-introduction authored: 2026-04-28 authored_by: design-team-member-name OR ai-agent-id status: ratified brand_voice_alignment: [confident, direct, professional] accessibility_targets: [wcag-2-2-aa, focus-visible] ai_consumption_hint: "When generating a button for a primary action, use this component. When the action is destructive, use button-danger instead." --- ``` The frontmatter is machine-readable; the body is prose-readable. AI agents consume the research through the substrate's [[mcp-substrate-protocol|MCP endpoint]] `[mcp-spec]` at decode time. Methods include `list_tokens`, `list_components`, `list_research`, and `describe`. An AI agent registers the substrate as an MCP server, then queries it during UI generation to align with the SMB's brand intent. Design systems that publish only token values and component shapes omit the rationale behind those choices. The substrate publishes both, in the same machine-readable tier, served through the same endpoint. ## Agnostic Editorial Standard The W3C Design Tokens Community Group format reached its 2025.10 stable specification in October 2025. Figma ships native DTCG import and export; Penpot has been DTCG-native since Penpot 2.x; Style Dictionary, Specify, and Tokens Studio all consume DTCG. On the consumer side: - **Figma** — via the Tokens Studio plugin or Figma's native variable system - **Penpot** — imports DTCG natively; the substrate-Penpot pairing is the fully-open-source design workflow the platform recommends to SMB customers who prefer a self-hostable editor - **Sketch** — via the Tokens Studio Sketch plugin - **Hand-authoring** — designers edit DTCG JSON directly; this is also the path most accessible to AI agents The customer chooses the editor; the substrate does not require a particular one. ## Baseline Primer Components The substrate imports IBM Carbon's primitive token vocabulary as the floor layer of every new instance. Color naming follows Carbon's convention (`gray-10` through `gray-100`). Type scale follows Carbon's productive and expressive families. Spacing follows Carbon's 8px grid. Focus ring follows Carbon's WCAG 2.2 AAA-conformant style. Brand-specific work happens at the semantic layer (`themes//`), not the primitive layer. SMB customers extend with brand overrides without re-learning a new component taxonomy. Carbon was chosen for three reasons: familiarity surface (wide accessible-design muscle-memory footprint among practitioners), accessibility floor (WCAG 2.2 AAA conformance built into primitive choices), and permissive licensing on the form (Carbon's token values are publicly documented; IBM Plex is permissively licensed; the naming convention is a documentation artefact, not a trademarked asset). What is not imported from Carbon: IBM Cloud-specific themes, React-specific component implementations, the IBM logo and "Carbon" wordmark, Carbon-specific component micro-interactions. A planned future milestone may introduce an alternative primitive bottom — Untitled UI (MIT-licensed) is a candidate for a second primitive layer in a subsequent release. That work is intended and subject to technical evaluation; no timeline is committed. Forward-looking statements about future milestones are subject to the cautionary factors described in `[ni-51-102]` and `[osc-sn-51-721]`. ## Sovereign Forking Procedure An SMB customer forks by cloning the source repository, building the substrate engine (a native Rust binary), initialising a vault from the canonical template, editing their brand's semantic layer in `themes/.json`, and running the bootstrap script to configure the service and TLS. The operator runbook at `vault-privategit-design/GUIDE-deploy-design-substrate.md` covers the full procedure. The customer ends up with a fully self-hosted, customer-owned design-system substrate. No SaaS dependency. No hyperscaler runtime. Their theme files and any research entries they author are their work product, in their Git repository, signed by their key. ## Structural Substrate Distinctions **Per-tenant Git ownership** requires a per-tenant signing identity (the customer's `allowed_signers` chain). Platforms hosted on shared infrastructure cannot accommodate this without becoming a Git hosting provider. **AI-readable research backplane in customer-owned form** requires per-customer hosting. A platform can publish its own design research; it cannot publish the SMB customer's research, because it does not host the SMB customer's design system. **Customer-rooted attestation.** The substrate's quarterly [[capability-ledger-substrate|Trustworthy System Attestation]] combines the [[worm-ledger-design|WORM ledger]], Sigstore Rekor anchoring `[sigstore-rekor-v2]`, and per-tenant `allowed_signers`. The resulting attestation covers the customer's design data — not the platform provider's controls. **Editor agnosticism.** Commercial design-system platforms have an incentive to keep the customer in their editor ecosystem. The substrate has no such incentive — DTCG is the common denominator. The four properties compound. Removing any one weakens the others. ## Excluded Operational Models The substrate is not a Storybook replacement. Storybook is a parallel renderer; the substrate owns its rendering. It is not a design editor competitor. Design editors (Figma, Penpot, Sketch) are the tools designers work in; the substrate is the canonical store those editors interoperate with via DTCG. It is not a SaaS platform. A managed-hosting option for SMB customers who prefer not to operate the service themselves is a planned future offering subject to operator capacity and customer demand; the substrate code will remain self-hostable in all cases. It is not a JavaScript-framework choice. Components are HTML+CSS+ARIA recipes; the customer's chosen framework consumes the recipe. It is not a container artefact. The substrate ships as a native binary deployed via systemd. ## See also - [[compounding-substrate]] - [[substrate-native-compatibility]] - [[customer-hostability]]