How tridenttech-web/ttc-design-system works
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: components Components · preview.js Preview setup · factbook-grid.stories.js Factbook grid · build-tokens.mjs Token build
Components 22
Storybook shell
Central host and UI control plane for the design system docs.
- Storybook · The interactive documentation shell that renders stories and MDX docs.
- Main config · Declares what Storybook loads and how the content surface is composed.
.storybook/main.js - Preview setup · Applies global decorators, parameters, and shared styling to every story.
.storybook/preview.js - Manager UI · Customizes the Storybook chrome and navigation experience.
.storybook/manager.js - 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 · Brand primitives for color, spacing, and typography maintained as token source files.
tokens/color.tokens.json - Token build · Transforms token JSON into consumable styles for the docs site.
scripts/build-tokens.mjs - Tokens CSS · CSS layer exposing the token system to stories and docs.
src/styles/tokens.css - App CSS · Site-wide presentation layer used by Storybook content.
src/styles/app.css
Docs & stories
Consumer-facing documentation, foundations, and component examples.
- Introduction · Landing page and entry point for the Storybook documentation experience.
src/Introduction.mdx - Foundations · Written guidance for principles, color, and typography.
src/docs/foundations/principles.md - Components · The main catalog of reusable UI patterns documented as Storybook stories.
src/components - Alert · Story entry for alert behavior and variants.
src/components/alert/alert.stories.js - Button · Story entry for button styles and states.
src/components/button/button.stories.js - Card · Story entry for card layout and composition patterns.
src/components/card/card.stories.js - Contact card · Story entry for the contact card with photo pattern.
src/components/contact-card-w-photo/contact-card-w-photo.stories.js - A11y messages · Story entry for accessibility messaging patterns.
src/components/accessibility-messages/accessibility-messages.stories.js - Factbook grid · A more specialized example that combines stories with supporting implementation code.
src/components/factbook/factbook-grid.stories.js - Factbook table · 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 · Bundling and local development toolchain used by the Storybook setup.
vite.config.js - Eleventy · Additional static-site generation or documentation assembly step.
eleventy.config.js - Pages deploy · Publishes the built Storybook site to GitHub Pages.
.github/workflows/storybook-pages.yml
Connections 21
- 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.