Architecture

Reference Value
Subject and boundary Getting a working checkout, finding where a change belongs and taking it through review. For contributors to the shared packages.
Verified source package.json, CONTRIBUTING.md, turbo.json, .gitattributes at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10; earlier pass checked November 7, 2026. Merge-queue steps from RELEASING.md §1.
Support state Maintained contributor commands at v0.40.0. Gallery runs Kit 3, TypeScript 6 and Vite 8; library/tooling checks use TypeScript 5.9.

Prerequisites

Tool Version and source Needed for
Bun 1.3.11 (.bun-version, packageManager); engines allow >=1.3.0 Install, scripts, tools
Node Node 22 in .nvmrc; root engine floor 22.17 Vite, Playwright server and type tools
Chromium bun run browser:install once Gallery browser suite
GitHub CLI Any current gh Release inspection and attestation checks only

No secrets or environment files are needed for local work. The documented Gallery controls are GALLERY_BROWSER_PORT (Gallery browser preview port, default 4173, must be 1 to 65535) and CI (Playwright reporters and forbidOnly).

First run

git clone https://github.com/yesid-dev/yesid.design.git
cd yesid.design
bun install --frozen-lockfile
bun run check
bun run test
bun run ci:tokens
bun run build
bun run dev

CI's check job installs, checks, tests, verifies token drift and then runs turbo run build. The local build script also regenerates tokens. dev serves the Gallery. For fast local loops, bun run test:changed runs the tests affected since the merge base with origin/main (see Testing, CI and generated-byte parity); it supplements the full CI gates. Workspaces are apps/* and packages/*; Turbo runs build, test and check per workspace, and dev is persistent and uncached. packages/tokens/tokens.json is a Turbo global dependency, so a token edit invalidates every cached task.

Where a change belongs

To change Edit Run before review
A colour, type size, spacing, radius, shadow or motion value packages/tokens/tokens.json bun run tokens:build, bun run ci:tokens, tokens tests; a new text size also joins the class merger (see ‣)
A token generator packages/tokens/src/generators/, packages/tokens/src/build.ts, or path handling in tools/build-tokens.ts Same as above
A component, frame, store, head or base CSS packages/ui/src/, packages/ui/base.css bun run --cwd packages/ui test, check, bun run api:report
A motion action or helper packages/motion/src/ Package test and check, api:report
A gate engine packages/gates/src/engines/ Package test and check, api:report
JSON-LD, sitemap, OG card, icons, headers, highlighting packages/seo-kit/src/ Package test and check, api:report
Analytics or web vitals packages/analytics/src/ Package test and check, api:report
Locale routing, Intl, typed copy packages/i18n-core/src/ Package test and check, api:report
Shared tsconfig, Svelte runes or Playwright projects packages/config/ bun run test:repository (no API report)
Release, API or token tooling tools/*.ts bun run test:repository, bun run check
A Gallery example or browser spec apps/gallery/src/, apps/gallery/tests/ Gallery test, bun run test:browser
CI or the setup action .github/workflows/, .github/actions/setup/ Repository trust-root contract (test:repository)

Generated files are never edited by hand: packages/tokens/tokens.css, packages/tokens/theme.css, packages/motion/src/tokens.ts, DESIGN.md (from tokens:build) and api-reports/*.api.md (from api:report).

Pull request workflow

  1. Reproduce the failure. Add the regression test in the package that owns the behavior, with neutral fixtures and no product names.
  2. Make the narrow change. If an export, type, Svelte prop or public CSS/JSON asset changed, run bun run api:report, read the diff and run bun run api:check.
  3. Add a .changes/<slug>.md fragment for anything a consumer can notice. CI rejects a changed API report without a new fragment for that package.
  4. Update the owning package README when a documented contract changes.
  5. Open one change per pull request against main. Say what was wrong, what changed and which commands ran. The aggregate ci check must pass; CODEOWNERS assigns every path to the maintainer. An approved PR merges through the main merge queue: gh pr merge <number> --repo yesid-dev/yesid.design --auto --squash. The queue reruns the required checks and squash-merges when they pass.

Commit messages state the outcome, for example fix(ui): keep the combobox label through the portal.

Supported app configuration

@yesid/config/tsconfig/svelte-kit.json supports TypeScript >=6 <7 and SvelteKit >=3 <4. Compose it after Kit 3's generated $app/tsconfig; pass kit.config.js to sveltekit(config) in Vite. The library config supports TypeScript >=5.9 <7. Gallery samples Kit 3.1.1, Svelte 5.57.2 and Vite 8.3.5; supported ranges are in the config README, and the product guide owns the composed boot/fonts/theme/language/header setup. A product keeps adapters, source inclusion, aliases, gate policy and deployment.