# tridenttech-web/ttc-design-system architecture

> Architecture diagram of the GitHub repository tridenttech-web/ttc-design-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tridenttech-web/ttc-design-system
- Repository: https://github.com/tridenttech-web/ttc-design-system

## Overview

1. **What this repo is**
   - This is not an application backend or product UI; it is a **design system documentation site** built around **Storybook** for Trident Tech’s web brand and components.

2. **Primary runtime and delivery model**
   - The main experience is a **local Storybook server** for interactive component preview and documentation.
   - The repository also includes a **GitHub Pages deployment workflow** (`.github/workflows/storybook-pages.yml`), so the published artifact is a static Storybook site.

3. **Storybook is the central shell**
   - The `.storybook/` directory is the architectural control plane:
     - `main.js` defines what Storybook loads.
     - `preview.js` applies global decorators/parameters and likely imports the shared styles.
     - `manager.js` customizes the Storybook UI chrome.
     - `ttc-theme.js` defines the design system’s Storybook theme.
   - In practice, this is the boundary between the design system content and the Storybook host application.

4. **Design token pipeline**
   - `tokens/*.json` is the source of truth for brand primitives such as **color, spacing, and typography**.
   - `scripts/build-tokens.mjs` suggests a build step that converts those JSON tokens into consumable styles.
   - `src/styles/tokens.css` is the generated or assembled CSS layer used by the docs/stories, making tokens available to all component previews.

5. **Shared styling layer**
   - `src/styles/app.css` provides the site-wide presentation layer for Storybook content.
   - The styling architecture appears to be token-first: raw tokens feed CSS, and CSS is then consumed by stories and docs.

6. **Component documentation area**
   - `src/components/` is organized by component namespace, with each folder containing stories for one design system piece.
   - Examples include `alert`, `button`, `card`, `contact-card-w-photo`, and `accessibility-messages`.
   - This folder is the main catalog of reusable UI patterns, each exposed through Storybook stories rather than a full application runtime.

7. **Specialized table/grid example**
   - `src/components/factbook/` contains `factbook-grid.stories.js` and `factbook-table-grid.js`.
   - This suggests at least one component includes a small amount of implementation code, not just story metadata, likely for a more complex content/layout pattern.

8. **Foundations and written guidance**
   - `src/docs/foundations/` contains Markdown docs for **principles, colors, and typography**.
   - These are the design-system “why” and “how” layers, complementing the component stories with non-interactive documentation.

9. **Introductory documentation**
   - `src/Introduction.mdx` serves as the Storybook landing page or entry point, framing the system for consumers.
   - MDX indicates the docs layer mixes prose with rendered components, which is typical for design systems.

10. **Build/tooling boundaries**
   - `vite.config.js` indicates Vite is part of the build toolchain, likely as Storybook’s bundler or supporting local development/build performance.
   - `package.json` and `package-lock.json` define the Node/npm dependency boundary for all tooling.

11. **Static-site generation support**
   - `eleventy.config.js` implies some static-site generation or documentation assembly outside Storybook’s default pipeline.
   - Even if Storybook is the main runtime, Eleventy suggests there is an additional static-content build concern in the repo.

12. **End-to-end flow**
   - The high-level flow is:
     - token JSON is maintained in `tokens/`
     - tokens are transformed into CSS/styles
     - Storybook loads global styles and theme configuration
     - component stories and MDX docs render within Storybook
     - the site is built and published to GitHub Pages

13. **How to think about the architecture diagram**
   - The diagram should center on **Storybook as the host**, with three major content inputs feeding it:
     - **design tokens**
     - **component stories/implementation**
     - **foundational docs**
   - Surrounding that are the **build scripts/configuration** and the **GitHub Pages deployment target**.

14. **Notable boundary**
   - There is no evidence of API services, databases, or app-state orchestration here.
   - This repo’s architecture is primarily about **documentation delivery, design token distribution, and component showcasing**.

Main entry points: [`src/components`](https://github.com/tridenttech-web/ttc-design-system/tree/main/src/components) (Components), [`.storybook/preview.js`](https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/preview.js) (Preview setup), [`src/components/factbook/factbook-grid.stories.js`](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/factbook/factbook-grid.stories.js) (Factbook grid), [`scripts/build-tokens.mjs`](https://github.com/tridenttech-web/ttc-design-system/blob/main/scripts/build-tokens.mjs) (Token build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storybook_shell["Storybook shell"]
  node_storybook["Storybook<br/>docs host"]
  node_storybook_main["Main config<br/>storybook config<br/>[main.js]"]
  node_storybook_preview["Preview setup<br/>storybook config<br/>[preview.js]"]
  node_storybook_manager["Manager UI<br/>storybook config<br/>[manager.js]"]
  node_storybook_theme["Theme<br/>[ttc-theme.js]"]
end

subgraph group_tokens["Tokens & styles"]
  node_token_sources["Token JSON<br/>design tokens<br/>[color.tokens.json]"]
  node_build_tokens["Token build<br/>token pipeline<br/>[build-tokens.mjs]"]
  node_tokens_css["Tokens CSS<br/>generated styles<br/>[tokens.css]"]
  node_app_css["App CSS<br/>global styles<br/>[app.css]"]
end

subgraph group_content["Docs & stories"]
  node_intro_mdx["Introduction<br/>mdx doc<br/>[Introduction.mdx]"]
  node_foundations["Foundations<br/>md docs<br/>[principles.md]"]
  node_component_catalog["Components<br/>story catalog"]
  node_alert_story["Alert<br/>component story<br/>[alert.stories.js]"]
  node_button_story["Button<br/>component story<br/>[button.stories.js]"]
  node_card_story["Card<br/>component story<br/>[card.stories.js]"]
  node_contact_story["Contact card<br/>component story"]
  node_accessibility_story["A11y messages<br/>component story"]
  node_factbook_story["Factbook grid<br/>complex story"]
  node_factbook_impl["Factbook table<br/>story support"]
end

subgraph group_build["Build & deploy"]
  node_vite["Vite<br/>build tool<br/>[vite.config.js]"]
  node_eleventy["Eleventy<br/>site builder<br/>[eleventy.config.js]"]
  node_deploy["Pages deploy<br/>github action"]
end

node_storybook_main -->|"loads"| node_storybook
node_storybook_preview -->|"decorates"| node_storybook
node_storybook_manager -->|"customizes"| node_storybook
node_storybook_theme -->|"brands"| node_storybook
node_token_sources -->|"inputs"| node_build_tokens
node_build_tokens -->|"generates"| node_tokens_css
node_tokens_css -->|"applied by"| node_storybook_preview
node_app_css -->|"applied by"| node_storybook_preview
node_intro_mdx -->|"renders in"| node_storybook
node_foundations -->|"documents"| node_storybook
node_component_catalog -->|"hosts"| node_storybook
node_alert_story -->|"part of"| node_component_catalog
node_button_story -->|"part of"| node_component_catalog
node_card_story -->|"part of"| node_component_catalog
node_contact_story -->|"part of"| node_component_catalog
node_accessibility_story -->|"part of"| node_component_catalog
node_factbook_story -->|"part of"| node_component_catalog
node_factbook_story -->|"uses"| node_factbook_impl
node_vite -->|"bundles"| node_storybook
node_eleventy -->|"assembles"| node_storybook
node_deploy -->|"publishes"| node_storybook

click node_storybook_main "https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/main.js"
click node_storybook_preview "https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/preview.js"
click node_storybook_manager "https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/manager.js"
click node_storybook_theme "https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/ttc-theme.js"
click node_token_sources "https://github.com/tridenttech-web/ttc-design-system/blob/main/tokens/color.tokens.json"
click node_build_tokens "https://github.com/tridenttech-web/ttc-design-system/blob/main/scripts/build-tokens.mjs"
click node_tokens_css "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/styles/tokens.css"
click node_app_css "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/styles/app.css"
click node_intro_mdx "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/Introduction.mdx"
click node_foundations "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/docs/foundations/principles.md"
click node_component_catalog "https://github.com/tridenttech-web/ttc-design-system/tree/main/src/components"
click node_alert_story "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/alert/alert.stories.js"
click node_button_story "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/button/button.stories.js"
click node_card_story "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/card/card.stories.js"
click node_contact_story "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/contact-card-w-photo/contact-card-w-photo.stories.js"
click node_accessibility_story "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/accessibility-messages/accessibility-messages.stories.js"
click node_factbook_story "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/factbook/factbook-grid.stories.js"
click node_factbook_impl "https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/factbook/factbook-table-grid.js"
click node_vite "https://github.com/tridenttech-web/ttc-design-system/blob/main/vite.config.js"
click node_eleventy "https://github.com/tridenttech-web/ttc-design-system/blob/main/eleventy.config.js"
click node_deploy "https://github.com/tridenttech-web/ttc-design-system/blob/main/.github/workflows/storybook-pages.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_storybook,node_storybook_main,node_storybook_preview,node_storybook_manager,node_storybook_theme toneBlue
class node_token_sources,node_build_tokens,node_tokens_css,node_app_css toneAmber
class node_intro_mdx,node_foundations,node_component_catalog,node_alert_story,node_button_story,node_card_story,node_contact_story,node_accessibility_story,node_factbook_story,node_factbook_impl toneMint
class node_vite,node_eleventy,node_deploy toneRose
```

## Components

### Storybook shell

Central host and UI control plane for the design system docs.

- **Storybook**: docs host · The interactive documentation shell that renders stories and MDX docs.
- [Main config](https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/main.js): storybook config · Declares what Storybook loads and how the content surface is composed. · `.storybook/main.js`
- [Preview setup](https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/preview.js): storybook config · Applies global decorators, parameters, and shared styling to every story. · `.storybook/preview.js`
- [Manager UI](https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/manager.js): storybook config · Customizes the Storybook chrome and navigation experience. · `.storybook/manager.js`
- [Theme](https://github.com/tridenttech-web/ttc-design-system/blob/main/.storybook/ttc-theme.js): storybook theme · Defines the design system branding for the Storybook UI. · `.storybook/ttc-theme.js`

### Tokens & styles

Source tokens, generated CSS, and shared presentation layers.

- [Token JSON](https://github.com/tridenttech-web/ttc-design-system/blob/main/tokens/color.tokens.json): design tokens · Brand primitives for color, spacing, and typography maintained as token source files. · `tokens/color.tokens.json`
- [Token build](https://github.com/tridenttech-web/ttc-design-system/blob/main/scripts/build-tokens.mjs): token pipeline · Transforms token JSON into consumable styles for the docs site. · `scripts/build-tokens.mjs`
- [Tokens CSS](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/styles/tokens.css): generated styles · CSS layer exposing the token system to stories and docs. · `src/styles/tokens.css`
- [App CSS](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/styles/app.css): global styles · Site-wide presentation layer used by Storybook content. · `src/styles/app.css`

### Docs & stories

Consumer-facing documentation, foundations, and component examples.

- [Introduction](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/Introduction.mdx): mdx doc · Landing page and entry point for the Storybook documentation experience. · `src/Introduction.mdx`
- [Foundations](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/docs/foundations/principles.md): md docs · Written guidance for principles, color, and typography. · `src/docs/foundations/principles.md`
- [Components](https://github.com/tridenttech-web/ttc-design-system/tree/main/src/components): story catalog · The main catalog of reusable UI patterns documented as Storybook stories. · `src/components`
- [Alert](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/alert/alert.stories.js): component story · Story entry for alert behavior and variants. · `src/components/alert/alert.stories.js`
- [Button](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/button/button.stories.js): component story · Story entry for button styles and states. · `src/components/button/button.stories.js`
- [Card](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/card/card.stories.js): component story · Story entry for card layout and composition patterns. · `src/components/card/card.stories.js`
- [Contact card](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/contact-card-w-photo/contact-card-w-photo.stories.js): component story · Story entry for the contact card with photo pattern. · `src/components/contact-card-w-photo/contact-card-w-photo.stories.js`
- [A11y messages](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/accessibility-messages/accessibility-messages.stories.js): component story · Story entry for accessibility messaging patterns. · `src/components/accessibility-messages/accessibility-messages.stories.js`
- [Factbook grid](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/factbook/factbook-grid.stories.js): complex story · A more specialized example that combines stories with supporting implementation code. · `src/components/factbook/factbook-grid.stories.js`
- [Factbook table](https://github.com/tridenttech-web/ttc-design-system/blob/main/src/components/factbook/factbook-table-grid.js): story support · Implementation used by the factbook story for richer grid/table behavior. · `src/components/factbook/factbook-table-grid.js`

### Build & deploy

Tooling that bundles, assembles, and publishes the site.

- [Vite](https://github.com/tridenttech-web/ttc-design-system/blob/main/vite.config.js): build tool · Bundling and local development toolchain used by the Storybook setup. · `vite.config.js`
- [Eleventy](https://github.com/tridenttech-web/ttc-design-system/blob/main/eleventy.config.js): site builder · Additional static-site generation or documentation assembly step. · `eleventy.config.js`
- [Pages deploy](https://github.com/tridenttech-web/ttc-design-system/blob/main/.github/workflows/storybook-pages.yml): github action · Publishes the built Storybook site to GitHub Pages. · `.github/workflows/storybook-pages.yml`

## Connections

- Main config → Storybook: loads · Storybook main config defines the host composition.
- Preview setup → Storybook: decorates · Preview setup applies global parameters and shared styling.
- Manager UI → Storybook: customizes · Manager config changes the UI chrome around the docs.
- Theme → Storybook: brands · Theme config controls the Storybook visual identity.
- Token JSON → Token build: inputs · Token JSON is the source of truth for generated styles.
- Token build → Tokens CSS: generates · Build step produces the token CSS consumed by stories.
- Tokens CSS → Preview setup: applied by · Global preview setup pulls in the token layer.
- App CSS → Preview setup: applied by · Shared app styling is loaded into the preview surface.
- Introduction → Storybook: renders in · The landing MDX page is served through Storybook.
- Foundations → Storybook: documents · Foundational prose is part of the Storybook docs layer.
- Components → Storybook: hosts · The component catalog is the primary content input to Storybook.
- Alert → Components: part of · Alert is one of the documented component entries.
- Button → Components: part of · Button is one of the documented component entries.
- Card → Components: part of · Card is one of the documented component entries.
- Contact card → Components: part of · Contact card with photo is one of the documented component entries.
- A11y messages → Components: part of · Accessibility messaging is one of the documented component entries.
- Factbook grid → Components: part of · Factbook grid is a specialized component example.
- Factbook grid → Factbook table: uses · The story relies on a supporting implementation module.
- Vite → Storybook: bundles · Vite supports local development and Storybook builds.
- Eleventy → Storybook: assembles · Eleventy suggests an additional static-content assembly path.
- Pages deploy → Storybook: publishes · GitHub Pages workflow deploys the built Storybook artifact.
