System inventory
Canonical map of the SpryDesign monorepo: packages, apps, tooling, CI, and boundaries. Source file: docs/SYSTEM.md.
Single reference for structure, packages, apps, tooling, docs, and automation in this monorepo.
In the Next.js docs app, the same content is rendered at /docs/system (sidebar: Foundations → System inventory).
Monorepo and toolchain
| Item | Details |
|---|---|
| Workspaces | apps/*, packages/*, tooling/* via pnpm (packageManager: pnpm 10.6.0). |
| Orchestration | Turborepo — dev, build, lint, test across packages. |
| Language and quality | TypeScript (strict), ESLint, Vitest + Testing Library + jsdom where needed. |
| Styling | Tailwind CSS v4 + PostCSS (shared via @spry/config). |
| Releases | Changesets — pnpm changeset, pnpm version-packages, pnpm release (npm publishing path). |
Packages (packages/)
| Package | Role |
|---|---|
@spry/tokens | Brand and semantic tokens in TypeScript; CSS variables source (styles.css); unit tests. |
@spry/theme | Light/dark (data-spry-theme), density, locale, SpryProvider / useSpry; createSpryTheme, extendSpryTheme, applySpryThemeDefinition; global styles and Tailwind entry; tenant theme JSON: parse/validate, fetchSpryTenantTheme, in-memory cache with getOrFetch, useSpryTenantThemeDefinition; tests. |
@spry/ui | React primitives on CSS variables (Radix-based): accordion, alert, avatar, badge, breadcrumb, brand-logo, button, card, checkbox, dialog, dropdown, empty, form, input, pagination, data-table, table, toast, popover, progress, radio-group, select, separator, skeleton, statistic, spin, switch, tabs, tag, textarea, timeline, tooltip, layout utilities; cn utils; re-exports @spry/icons. |
@spry/icons | Icon set consumed by UI. |
@spry/patterns | Composed flows: AuthForm, DashboardLayout, HeroCta; Storybook stories; Vitest for all three. |
@spry/config | Shared TSConfig, ESLint, and Tailwind presets for apps and packages. |
Apps (apps/)
| App | Role |
|---|---|
@spry/docs | Next.js documentation site (port 3002): getting started, tokens, theming, architecture, philosophy, troubleshooting, contributing, changelog, design resources, component catalog (registry + previews), patterns, recipes, etc. |
@spry/next-web | Next.js consumer sample (port 3001) — validates the design system in the App Router. |
@spry/web | Vite consumer sample — theme switching and pattern demos. |
Tooling (tooling/)
| Tool | Role |
|---|---|
@spry/storybook | Storybook for UI and patterns; a11y and essentials addons; Playwright visual regression (test:visual / test:visual:update). |
Static docs and brand
| Location | Contents |
|---|---|
docs/brand/ | Markdown brand specs: BRAND_GUIDE, COLOR_SPEC, TYPOGRAPHY_SPEC, README. |
assets/branding/ | Logos, fonts — source assets as provided by design. |
CI (.github/workflows)
| Workflow | Purpose |
|---|---|
ci.yml | On push/PR: pnpm install --frozen-lockfile, pnpm build, pnpm lint, pnpm test, Storybook static build, Playwright Chromium install, visual regression tests. |
release.yml | Changesets-driven release path (versioning and npm publish when configured). |
Also: CODEOWNERS, pull request template.
End-to-end delivery
- Design tokens → theme layer (including optional multi-tenant / remote JSON theme pipeline) → UI primitives → patterns → example apps.
- Documentation — Next.js docs site plus markdown brand docs under
docs/brand/. - Storybook for components and patterns.
- Quality gates — lint; unit tests (tokens, theme, ui, patterns); CI build; Storybook build; visual tests.
Outside this repository (by design)
| Concern | Notes |
|---|---|
| npm registry | You run Changesets / pnpm release when ready to publish packages. |
| Hosting | Production hosting for docs and sample apps is your choice (e.g. Vercel); the repo does not mandate a host. |
| Tenant product logic | Tenant admin UI, authentication, and your APIs live in your applications; the design system supplies theme parsing, fetch, cache, and UI primitives only. |
Layer diagram (mental model)
tokens → theme → ui → patterns → apps
For interactive documentation, run pnpm dev and open the @spry/docs app; for component exploration in isolation, run pnpm storybook.