Architecture

Reference Value
Subject and boundary What the repository is, the eight packages and the private Gallery, how they reach products, and what each product keeps.
Verified source README.md, each package's package.json and README under packages/, apps/gallery at tag v0.47.0. Verified tag v0.47.0, commit 451e8014c3977f4a971d56221b94a5011eaffe23, checked 2026-11-16.
Support state Eight lockstep source-shipped packages at v0.47.0. Gallery is a private Kit 3 app, version 0.1.0.

System context

flowchart LR
  subgraph repo["yesid.design"]
    TJ["packages/tokens/tokens.json"] --> BT["tools/build-tokens.ts"]
    BT --> GEN["tokens.css, theme.css, motion tokens.ts, DESIGN.md"]
    GEN --> PK["8 source-shipped packages"]
    PK --> GAL["apps/gallery (private)"]
    PK --> API["api-reports/"]
  end
  PK --> WF["release.yml"]
  WF --> REL["GitHub Release: 8 tgz + provenance"]
  REL -->|"exact URL pins + bun.lock integrity"| YD["yesid.dev"]
  REL -->|"exact URL pins + bun.lock integrity"| TR["Transit"]
  REL -->|"exact URL pins + bun.lock integrity"| YL["yesid.login"]

The repository is a Bun and Turborepo monorepo. Packages ship TypeScript, Svelte, JavaScript and CSS source; consumers compile them. Nothing is published to a registry. Three products consume releases: yesid.dev, Transit and the public yesid-dev/yesid.login app, which installs @yesid/ui, @yesid/tokens, @yesid/motion, @yesid/seo-kit and @yesid/analytics. Each product pins one release in its own package URLs, and its own records name which. yesid.dev and Transit install all eight packages, and yesid.login installs five. The supported app target is SvelteKit 3 with TypeScript 6, Svelte >=5.57.1, Node >=22.17, Vite 8 and Tailwind CSS v4; the complete build contract is in the product guide and config README. yesid.login sits outside that target: it is a Cloudflare Worker whose sign-in pages are a plain Svelte 5 and Vite client without SvelteKit. It imports UI components, @yesid/ui/base.css, token CSS and JSON, and seo-kit's icon and share-card helpers at build time, uses the analytics client on its sign-in pages and the analytics relay in its Worker, and installs motion only as the UI peer. @yesid/ui's only framework peer is Svelte 5, and neither UI nor motion source imports from SvelteKit; its other peers are the same-release tokens, motion and seo-kit. The product guide does not cover that use; yesid.login's own records own its verification.

Packages

Package Owns Public entry points Depends on
@yesid/tokens DTCG source, generated CSS and Tailwind theme, bundled fonts; private parser/build engine ./tokens.json, ./tokens.css, ./theme.css, ./fonts.css, ./fonts, ./generators/design-md none
@yesid/ui Svelte 5 primitives, brand components, page frames, shell/head, shared state, class merging and opt-in styles ., ./brand, ./blueprints, ./cn, 12 primitive families (Badge, Button, Card, Collapsible, Combobox, Footer, Resizable, Scroll Area, Separator, Sheet, Skeleton, Tabs), ./layout, ./state, ./head, ./feedback, ./table, ./base.css, ./station-tabs.css, ./boot.json bits-ui, paneforge, tailwind-merge, tailwind-variants, clsx, Lucide, tw-animate-css; peers Svelte 5 and same-release tokens, motion, seo-kit
@yesid/motion Two-tier motion policy, reduced-motion store, actions, GSAP, Lenis, ticker and view-transition helpers, generated motion tokens, opt-in CSS ., ./actions, ./policy, ./tokens, ./stores/reducedMotion, seven ./utils/* subpaths, ./lenis.css, ./ripple.css, ./tap-feedback.css GSAP, Lenis; peer Svelte 5
@yesid/gates Policy-neutral brand and quality engines and the bounded filesystem walk . none
@yesid/seo-kit JSON-LD, sitemap and robots, content-derived share copy, share card, icons, security headers, server-side highlighting ., ./jsonld, ./sitemap, ./share-copy, ./og, ./og/fonts, ./og/files, ./icons, ./headers, ./highlight peers same-release tokens, Satori, optional Shiki 4.x
@yesid/analytics Cookieless Plausible measurement, server-side event relay and web-vitals collection ., ./client, ./config, ./relay, ./vitals @plausible-analytics/tracker
@yesid/i18n-core Framework-free locale routing, cached Intl formatting, typed copy . none
@yesid/config TypeScript presets, Svelte runes policy, Playwright projects and accessibility checks ./package.json, ./tsconfig/*.json, ./turbo/base.json, ./svelte/project-runes.js, ./playwright optional peers Playwright, axe
Gallery (apps/gallery, private 0.1.0) Renders the workspace packages; owns rendered integration and browser tests never released workspace packages

Contracts by subject: Tokens, theme and CSS cascade, UI components, class merging and shell, Motion, SEO, analytics, i18n and gates.

Ownership rules

Rule Contract
No app conditionals Nothing in a package branches on which product uses it. A difference that cannot be a prop with a default stays in the product.
One direction Changes start here and reach products through releases. A product never patches installed package code; it upstreams the fix and takes the next release.
Exact pins Each product pins one release tag in every package URL; every upgrade is a reviewed pull request in that product. No ranges, branches or automatic sync.
Promote at two A component or composed pattern moves into a package once two products need the same contract.
Brand values Palette, type and motion doctrine are the owner's call.
The packages own Each product owns
Rendering mechanics, tokens, shared state and actions, policy-neutral engines, release integrity Copy, content, locale values, routes, analytics domain and events, CSP directive list, gate policy, deployment and product acceptance

Section state ownership

The package owns an origin-wide remembered expand-all choice, section registration, pre-paint geometry and readable startup recovery. A bulk-enabled page with at least two content sections starts expanded on first visit with a neutral Collapse all control; after a stored Collapse all the control is orange. The TOC starts open. Bulk actions write collapsed or expanded to localStorage['sections-choice']; individual toggles and jumps do not. Products own local copy, Back/locale reading-position integration, storage disclosures and real-caller verification. The UI components, class merging and shell own the detailed threshold, fallback, pending and scanner rules.

Integration constraints