Diff: substrate/design-system-substrate
From 583f642 to 583f642
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "Design-system substrate" | title: "Design-system substrate" |
| slug: design-system-substrate | slug: design-system-substrate |
| category: substrate | category: substrate |
| type: topic | type: topic |
| quality: complete | 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." | 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 | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| last_edited: 2026-05-15 | last_edited: 2026-05-15 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| cites: | cites: |
| - mcp-spec | - mcp-spec |
| - sigstore-rekor-v2 | - sigstore-rekor-v2 |
| - c2sp-tlog-tiles | - c2sp-tlog-tiles |
| - ni-51-102 | - ni-51-102 |
| - osc-sn-51-721 | - osc-sn-51-721 |
| paired_with: design-system-substrate.es.md | 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. | 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. | 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 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. | 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 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 | ## Immutable Vault Architecture |
| The substrate's content lives in a per-tenant vault directory: | The substrate's content lives in a per-tenant vault directory: |
| ``` | ``` |
| <tenant-vault>/ | <tenant-vault>/ |
| ├── tokens/ DTCG primitive + semantic + component layers | ├── tokens/ DTCG primitive + semantic + component layers |
| ├── components/ HTML+CSS+ARIA recipe files | ├── components/ HTML+CSS+ARIA recipe files |
| ├── themes/ per-brand semantic-layer overrides | ├── themes/ per-brand semantic-layer overrides |
| ├── research/ AI-readable design-decision rationale (markdown) | ├── research/ AI-readable design-decision rationale (markdown) |
| └── exports/ derived caches (Figma, Tailwind, Style Dictionary) | └── 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 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 (service-fs). 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]`. | 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 (service-fs). 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 | ## Machine-Readable Context Backplane |
| The `research/` directory is the substrate's most structurally novel element. Every design decision lives as a structured markdown file: | 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 | schema: foundry-design-research-v1 |
| component_or_token: button-primary | component_or_token: button-primary |
| decision_type: component-introduction | decision_type: component-introduction |
| authored: 2026-04-28 | authored: 2026-04-28 |
| authored_by: design-team-member-name OR ai-agent-id | authored_by: design-team-member-name OR ai-agent-id |
| status: ratified | status: ratified |
| brand_voice_alignment: [confident, direct, professional] | brand_voice_alignment: [confident, direct, professional] |
| accessibility_targets: [wcag-2-2-aa, focus-visible] | accessibility_targets: [wcag-2-2-aa, focus-visible] |
| ai_consumption_hint: "When generating a button for a primary | ai_consumption_hint: "When generating a button for a primary |
| action, use this component. When the action is destructive, use | action, use this component. When the action is destructive, use |
| button-danger instead." | button-danger instead." |
| --- | --- |
| ``` | ``` |
| The frontmatter is machine-readable; the body is prose-readable. AI agents consume the research through the substrate's 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. | The frontmatter is machine-readable; the body is prose-readable. AI agents consume the research through the substrate's 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. | 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 | ## 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. | 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: | On the consumer side: |
| - **Figma** — via the Tokens Studio plugin or Figma's native variable system | - **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 | - **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 | - **Sketch** — via the Tokens Studio Sketch plugin |
| - **Hand-authoring** — designers edit DTCG JSON directly; this is also the path most accessible to AI agents | - **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. | The customer chooses the editor; the substrate does not require a particular one. |
| ## Baseline Primer Components | ## 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. | 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/<brand>/`), not the primitive layer. SMB customers extend with brand overrides without re-learning a new component taxonomy. | Brand-specific work happens at the semantic layer (`themes/<brand>/`), 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). | 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. | 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]`. | 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 | ## 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/<smb-brand>.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. | 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/<smb-brand>.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. | 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 | ## 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. | **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. | **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 Trustworthy System Attestation combines the 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. | **Customer-rooted attestation.** The substrate's quarterly Trustworthy System Attestation combines the 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. | **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. | The four properties compound. Removing any one weakens the others. |
| ## Excluded Operational Models | ## Excluded Operational Models |
| The substrate is not a Storybook replacement. Storybook is a parallel renderer; the substrate owns its rendering. | 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 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 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 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. | It is not a container artefact. The substrate ships as a native binary deployed via systemd. |
| ## See also | ## See also |
| - [[compounding-substrate]] | - [[compounding-substrate]] |
| - [[substrate-native-compatibility]] | - [[substrate-native-compatibility]] |
| - [[customer-hostability]] | - [[customer-hostability]] |