# Sylhet Design System — consolidated maintained guides
Generated by scripts/build-layout-catalog.mjs. Read AGENTS.md for current workflow.
The complete 200-layout data lives separately in data/layouts.json; this file consolidates the prose guides and license, not the full asset or layout registry.
# Sylhet Design System
Quiet structure. Precise type. Optional sound.
Sylhet Design System (SDS) is a minimal design system for human and AI builders: a small modern CSS/JavaScript layer, a preserved legacy library, practical documentation and **200 curated layout specifications across 20 families**, with [runnable composition scaffolds](previews/index.html). Start with white, near-black and one restrained green or orange accent. Compositions differ through reading sequence, proportions and evidence.
By **Z7 Studio** and **Mustafejur Rahman — Founder, Lead Director & Developer**. [LICENSE](LICENSE) permits personal and nonprofit use. Selling websites, commercial client work and other business use require prior written permission from Z7 Studio. Teams can seek permission or support through [z7.studio](https://z7.studio).
## Start
Copy `sylhet/` into your project's public `system/` directory. Serve over HTTP; module and asset fetching requires a proper server.
```html
```
Replace the sample copy and populate real work before publishing. The system supplies styling and optional interactions, not your content or backend.
## Plain-English names
Names now use plain English for international readers. The five sound packs were renamed: `kagoj` → `paper`, `kath` → `wood`, `pani` → `water`, `kach` → `glass`, `pathor` → `stone`. For one release the sound API still accepts the old pack IDs, logs a console warning and maps them to the new names; update your code before the next release. Place names such as Sylhet remain only as origin credits.
## Reference
| Need | Guide |
| --- | --- |
| Setup and implementation order | [Getting started](docs/getting-started.md) |
| Visual principles | [Foundations](docs/foundations.md) |
| Canonical names and values | [Tokens](docs/tokens.md) |
| Token source, exports and high contrast | [Tokens: source and exports](docs/tokens.md#token-source-and-exports) |
| Type scale and Bangla text | [Type scale](docs/typography-scale.md) |
| Icon sprite, module and element | [Icons](docs/icons.md) |
| Component library (navigation, forms, overlays, tabs, menus, feedback, data display, layout) | [Components](docs/components/README.md) · [live demos](recipes/components/index.html) |
| Eight optional accent combinations | [Place palettes](docs/place-palettes.md) |
| Composition and responsive spans | [Layout](docs/layout.md) |
| Type hierarchy and writing | [Typography](docs/typography.md) |
| Markup, states and behavior boundaries | [Components](docs/components.md) |
| Semantics and keyboard | [Accessibility](docs/accessibility.md) |
| Crop, performance and rights | [Images](docs/images.md) |
| Glyphs, motion preferences and Lottie | [Motion](docs/motion.md) |
| Exact opt-in audio API | [Sound](docs/sound.md) |
| Source and integration | [Code](docs/code.md) |
| AI workflow | [AI guide](docs/ai.md) |
| 200 compositions | [Catalogue](docs/layout-catalog.md) · [JSON](data/layouts.json) · [schema](docs/layout-schema.md) |
| Modern APIs and asset discovery | [Canonical registry](registry.json) |
| Release checks | [Quality](docs/quality.md) |
| Prior art and official references | [Evidence](docs/evidence.md) |
[llms.txt](llms.txt) is a short AI index; [llms-full.txt](llms-full.txt) is a consolidated guide. They are ordinary text files, not an MCP server or a framework installer.
## Run and rebuild
Run `npm run dev` for the modern showcase at `http://localhost:4321`. The server exposes this system under `/system/`. `npm run build` rebuilds the showcase and its downloadable package; `npm run check` runs the dedicated showcase checks. These are local project scripts, not a publishing service.
| Command | Scope |
| --- | --- |
| `npm run catalog` | Generate 200 composition specifications, human index and consolidated AI guide |
| `npm run previews` | Render 200 responsive HTML scaffolds with clearly labeled sample content |
| `npm run lottie` | Generate and enrich the original Lottie library |
| `npm run legacy:serve` | Serve preserved legacy reference examples |
| `npm run legacy:themes` | Rebuild legacy theme CSS |
| `npm run legacy:assets` | Rebuild legacy SVG icons, patterns and doodles |
| `npm run legacy:recipes` | Rebuild the original nine HTML recipes |
| `npm run legacy:images` | Rebuild the legacy image-prompt document |
| `npm run legacy:docs` | Write only `docs/legacy-reference.html` and `data/legacy-registry.json` |
| `npm run legacy:sounds` | Explicit legacy sound generation; inspect script prerequisites first |
The modern build does not invoke legacy documentation generation. The catalogue generator checks unique IDs, unique sequences, known section types and desktop span totals; it does not establish the quality of 200 finished sites.
After changing a recipe, run `npm run catalog` then `npm run previews`. Preview forms are demonstration fields without submission, placeholders are explicit and sample images are generated studies. Treat these as runnable composition starting points, then supply real content, implement application behavior and perform browser/accessibility review.
Modern pages load `sylhet/sds.css` and `sylhet/sds.js`; [registry.json](registry.json) describes that implemented contract. The older recipes, reference pages and [data/legacy-registry.json](data/legacy-registry.json) use separate `sy-*` APIs. Historical README and AI instructions are preserved in [docs/legacy/](docs/legacy/README-v0.1.md); their feature counts and compulsory questionnaire do not describe the modern layer.
The modern CSS self-hosts Inter and Geist Mono from `sylhet/fonts/`, with their OFL notices. Modern semantic Lottie uses the bundled runtime in `sylhet/vendor/` with its own license notice; legacy modules may load external fonts or a player. Read source before choosing your self-hosting strategy. Third-party fonts, photography, trademarks and animations keep their own rights and notices.
## Recreate the expressive showcase
The main page uses the public `initExpressivePage` preset, the same counted opening, orange block wipe, colorful word grid, square circuit, five Lottie studies, gravity words, square actions and closing scenes shipped in SDS. Start from [the expressive recipe](recipes/expressive/index.html), [motion atlas](recipes/motion-atlas.html), [motion contract](docs/expressive-motion.md) or [complete reproduction prompt](prompts/recreate-expressive-site.md). The expressive starter ZIP contains the complete five-page running example.
## Human layout tools
The showcase now includes `/layouts/` (12 distinct, three-page websites to study) and `/designer/` (local drag/drop page parts, responsive previews, JSON import/export, AI brief and linked static website export). These complement the 200 individual page compositions. See [website studies](docs/website-layouts.md) and [the layout desk](docs/designer.md). Optional standalone tools: `recipes/layouts.html` and `recipes/designer.html`.
MCP is implemented as an optional separate package. The website works without it. The [implementation](docs/mcp-plan.md) and [hosting guide](docs/deploy-mcp-free.md) describe local use and an optional remote release; nothing is deployed. Hosting has finite free quotas. Model usage and new sound generation have separate costs.
Deploy the complete static folder with the [website deployment guide](docs/deploy-website.md). Set SDS_SITE_ORIGIN to your own domain before building an absolute sitemap/canonical; the portable build does not ship localhost metadata.
## Independent deployment packages
Read [the complete deployment overview](docs/deploy.md). `deployments/website/` is ready for its own GitHub/Vercel project with Cloudflare DNS. `deployments/mcp/` is a separate optional local server or Cloudflare Worker. Either can remain undeployed. Website builds have no MCP dependency. Source refresh: `npm run mcp:prepare`; separate exports: `release:website` and `release:mcp`. Both packages include their own GUIDE.md.
---
# Build with Sylhet Design System
Read `README.md`, `docs/getting-started.md`, `docs/ai.md`, and `LICENSE`. User instructions take precedence. The old mandatory questionnaire is retired: when the brief is sufficient, build immediately and state reasonable assumptions. Ask only for missing facts that materially change the result.
## Default brief
Use a minimal white or warm-white ground, near-black ink and one restrained green **or** orange accent. Respect user colors and use them minimally. Let typography, space and composition make the identity. Default to calm motion, sound off, no ambient bed, no companion cursor and no ornamental pattern. Do not fill every available slot.
Choose green as a starting point for nature, community, care, learning or a calm voice; choose orange for creative work, making, warm materials or an expressive voice. These are heuristics, not restrictions. Supplied brand colors win. SDS's own identity uses green and orange; a user-approved composition may use both sparingly with a clear primary action. Eight optional place palettes are documented in `docs/place-palettes.md`; they require explicit extra CSS and are never activated by default. Do not turn accent selection into a mandatory questionnaire.
Modern entry points are `sylhet/sds.css` and `sylhet/sds.js`: `--sds-*`, `.sds-*`, `data-sds-*`. `registry.json` discovers that implemented contract and its docs/assets. Read source before using an undocumented selector or method. Legacy `sylhet/sylhet.css`, `sylhet/sylhet.js`, `sy-*` and `data/legacy-registry.json` remain separate APIs with different defaults. Do not accidentally load both complete stylesheets. `docs/legacy/` is historical material, not current instructions.
## Workflow
1. Identify the reader, primary task, real content and supplied restrictions. Never invent clients, metrics, testimonials, prices, credentials or contact addresses.
2. Select `data/layouts.json` by intent, content budget and available imagery. Read complete section specs. These 200 recipes are specifications, not 200 prebuilt or individually browser-tested websites.
3. Write semantic HTML in reading order, then apply grid spans with readable local CSS. Adapt unsupported sections to real content. Color swaps do not create new compositions.
4. Reuse documented tokens and primitives. Keep structure, styles, behavior and data in legible files. Avoid inline event handlers and giant opaque generated blobs.
5. Add motion only for hierarchy or feedback. Sound needs an explicit visitor gesture. A preview click permits one preview, not global sound. A success cue requires an actually successful operation; client validation is not a completed submission.
6. Run `docs/quality.md` checks. Report what ran, what was observed, and limitations. Schema validation is not browser QA or an accessibility audit.
## Accessibility and assets
Provide one page `h1`, logical headings, named navigation, a skip link, labeled fields, associated errors, visible focus, links for navigation and buttons for operations. Preserve DOM reading and focus order. Support keyboard, touch, zoom, reduced motion, missing images, unavailable audio and JavaScript failure. Never communicate state through color, motion or sound alone.
Set real image dimensions and appropriate alt. Hide decorative Lottie from assistive technology and provide a static fallback. Persistent movement needs pause control. Check asset manifests and provenance; never invent filenames or assume third-party rights. A proposed pattern is not a shipped widget.
## Provenance and permission
Credit **Sylhet Design System · Z7 Studio · Mustafejur Rahman, Founder, Lead Director & Developer**. Preserve source notices and visible site attribution. Personal/nonprofit use is permitted under `LICENSE`. Selling websites, paid client work or other business use requires prior written permission. Business-oriented examples do not grant commercial rights. Small businesses or development teams facing financial constraints can seek support or permission through **https://z7.studio**; do not invent a mailbox or promise approval.
Do not claim SDS invented design-system sound: Material 2 published dedicated guidance. See `docs/evidence.md`. `llms.txt` is the discovery index; `llms-full.txt` consolidates maintained guides, not the entire layout JSON. `registry.json` describes modern APIs and discovery paths; `data/layouts.json` describes composition specifications; `data/legacy-registry.json` preserves the old API inventory.
---
# Getting started
Build a complete static page around the reader's task before adding effects. Sylhet supplies visual grammar and inspectable code; content, server behavior, permissions and final accessibility remain project responsibilities.
## Choose an entry point
For new pages use `sylhet/sds.css` and `sylhet/sds.js`. Copy the entire `sylhet/` directory to `/system/sylhet/` when following these examples. Relative folders let the sound module find its manifest and samples. Serve the modern showcase with `npm run dev` or use your application server. `registry.json` provides exact API and asset discovery paths; `data/legacy-registry.json` preserves the older contract.
The CSS supplies tokens, base rules and composition primitives. The module wires glyph interactions, semantic Lottie instances, declarative scenes and optional menu disclosures, and exports sound helpers. The whole-page expressive preset is an explicit separate entry point described in [Recreate the SDS showcase](expressive-motion.md). It does not create form endpoints, modal dialogs, tablists, charts or a data store. Read [components](components.md) before inferring a widget exists. Include static Lottie posters in HTML and choose real manifest names as described in [motion](motion.md).
Legacy `sylhet/sylhet.css` and `sylhet/sylhet.js` power nine original recipe HTML files and the `sy-*` ecosystem. Use those when deliberately adapting legacy examples. Loading both complete bases can change global typography and resets.
## Select a composition
1. Define the primary task and list the real content available.
2. Search `data/layouts.json` by `intent`, budget and image requirements.
3. Read sections in order. A photo-led recipe needs meaningful photographs.
4. Build semantic HTML, then implement grid spans with scoped local CSS. JSON metadata is not automatic CSS.
5. Collapse in source order; preserve evidence, labels and actions.
Use `data-sds-accent="green"` or `"orange"`. Use `data-sds-scheme="dark"` for the dark token set and `data-sds-motion="still"` to remove modern animation and transitions. Calm is the restrained default; modern audio remains off until explicitly enabled.
When no brand direction is supplied, green is a useful starting point for nature, community or a calm voice; orange suits creative work, making or a warmer expressive voice. Respect an already selected identity. [Optional place palettes](place-palettes.md) provide eight deliberate alternatives by loading a separate stylesheet; they do not change neutral grounds and none is automatically active.
## Complete the page
Write a specific title, one `h1`, useful headings, descriptive links and a real next step. Include a skip link and footer attribution. Add actual image dimensions and check rights. Implement form processing and truthful pending, success and error states. A demo form must state its behavior visibly.
Use `data-sds-float` for a deliberate floating text block, or the showcase's `data-sds-text="gravity"` root preset for ordinary copy and navigation. Square actions are supplied by the entry module. Fields, code and essential status messages stay still. The older short glyph substitution remains a separate effect. See [the exact showcase contract](expressive-motion.md). Add sound through [the documented API](sound.md), with visitor control. Sound and reduced-motion preferences are independent.
Before publication, perform [quality checks](quality.md), replace placeholders and confirm [usage permission](license.md). Report observed results and remaining limitations; do not claim certification from a token check or successful build.
---
# Foundations
SDS combines readable content, deliberate proportions and quiet feedback. Its cultural origin is authorship, not a requirement to decorate every page. Type, spacing, sequence and a precise action can carry the system on their own.
| Decision | Default | Reason to change |
| --- | --- | --- |
| Ground and ink | Near white and near black | A real brand or dark reading context |
| Accent | Small orange or green use | User-supplied brand color |
| Hierarchy | Large clear headings, readable body | Dense tasks need a smaller local scale |
| Shape | Quiet surfaces and pill actions | Existing product shape language |
| Images | Relevant, captioned, purposeful | Omit images that add no information |
| Motion | Short, local feedback | Stillness better serves the task |
| Sound | Off and optional | Explicit visitor enable or preview |
| Ornament | None | A specific editorial purpose |
## Choose an accent from the brief
SDS's own identity uses green and orange. For most consuming pages, choose one as the primary accent and keep the amount of color small. The user's selected brand colors take precedence; do not replace a supplied identity with a stock palette just because a category suggests one.
| Brief signal | Useful starting choice | How to apply it |
| --- | --- | --- |
| Nature, community, care, learning, a calm voice | Green | Small action fills, selected indicators or one short emphasis |
| Creative work, making, warm materials, an expressive voice | Orange | One precise action or occasional short emphasis |
| Supplied brand colors | The supplied identity | Map roles deliberately and verify actual text/background pairs |
| A deliberate alternative tonal direction | An optional place palette | Load it explicitly; preserve neutral grounds and restrained use |
These are starting heuristics, not rules that assign a personality to every organization. If a clear brief supports a choice, make it and state the assumption briefly. Do not stop to ask a mandatory color questionnaire. Green and orange can both appear in SDS's identity or in a user-approved composition, while hierarchy should still identify the primary action clearly.
[Eight optional place palettes](place-palettes.md) change only three accent tokens. Their city-inspired names describe design associations, not historical or cultural certification. A palette change is not a new composition.
## Select relationships
Avoid turning everything into equal cards. Ruled lists, a reading column, a date rail, a table or asymmetrical figures often explain content better. A prominent action does not require a bright section. First use size, measure, position and space to establish hierarchy.
Give a title breathing room without forcing every hero to fill a viewport. Show a real informative image before an arbitrary gradient. A reference needs an index; a case study needs context and evidence; a form needs expectations and recoverable errors. Do not add unsupported metrics, testimonials or an FAQ to fill a pattern.
## Be truthful
Use specific nouns and verbs. Explain price, access requirements, timezone and availability when relevant. Distinguish measured results from goals, demos from live services, downloads from external links and local selection from saved preference. Do not invent clients, awards, statistics or contact details.
## Adapt responsibly
The catalogue offers starting arguments, not compulsory templates. Remove unsupported sections and add necessary access or consent context. Record why an adaptation exists so another person or AI can maintain it. A coherent page matters more than preserving a recipe verbatim.
The modern layer has a smaller contract than the legacy library. Trace claims to source, a manifest, a demonstrable behavior or a labeled specification. Credit [Z7 Studio](https://z7.studio) and Mustafejur Rahman, Founder, Lead Director & Developer. Read [LICENSE](../LICENSE) before deployment.
---
# Tokens
Canonical modern definitions live in [`sds.css`](../sylhet/sds.css). They differ from legacy `--sy-*`. Inspect computed values when debugging nested overrides.
| Token | Light default | Role |
| --- | --- | --- |
| `--sds-paper` | `#fafaf7` | Page ground |
| `--sds-surface` | `#ffffff` | Bounded surface |
| `--sds-ink` | `#191b17` | Main text, strong action |
| `--sds-muted` | `#63665f` | Readable secondary text |
| `--sds-line` | `#dedfd8` | Decorative separators only |
| `--sds-border-strong` | `#868980` | Field and secondary button borders (3:1 or more on paper and surface) |
| `--sds-orange-srgb` | `#f15c2b` | Portable orange identity fallback |
| `--sds-orange` | sRGB fallback / vivid P3 | Orange identity fill |
| `--sds-accent` | `var(--sds-orange)` | Small emphasis fills |
| `--sds-accent-text` | `#b9310a` | Accent text and focus |
| `--sds-on-accent` | `#151813` | Text on accent fill |
| `--sds-soft` | `#fcebe2` | Subtle emphasis ground |
## Status colors
Each status has a fill token for borders and marks and a `-text` token for words. Every `-text` token has at least 4.5:1 contrast against paper and surface in both schemes. Never rely on color alone: pair a status with a word such as "Saved" or "Error".
| Token | Light | Dark | Role |
| --- | --- | --- | --- |
| `--sds-success` | `#2f9e44` | `#4cc35f` | Success fill or border |
| `--sds-success-text` | `#2b6a1a` | `#7fd28a` | Success text |
| `--sds-warning` | `#b87a00` | `#e8a317` | Warning fill or border |
| `--sds-warning-text` | `#8a5300` | `#f2c04a` | Warning text |
| `--sds-danger` | `#d93a2b` | `#f0614f` | Danger fill or border |
| `--sds-danger-text` | `#b42318` | `#ff8a7a` | Danger text and danger button ground |
| `--sds-info` | `#3b82c4` | `#5aa2e6` | Info fill or border |
| `--sds-info-text` | `#1d5fa0` | `#8cc4ff` | Info text |
## Color scheme
`:root` declares `color-scheme: light`. `data-sds-scheme="dark"` declares `color-scheme: dark` and switches the neutral, accent-text, status and shadow tokens. `data-sds-scheme="auto"` applies the same dark values only when the visitor's system prefers a dark scheme, and stays light otherwise. In dark, `--sds-border-strong` is `#7d8473`.
`data-sds-accent="green"` sets accent to `#bfdc4a`, accent-text to `#3f650c`, and soft to `#edf2df`. Fill and text tokens serve different roles: bright green is unsuitable for small text on white. Dark scheme overrides paper, surface, ink, muted, line, border-strong, accent-text, status and shadow tokens; green+dark has its own text override. Check actual foreground/background pairs, including hover, focus, transparency and photographic backgrounds. Tokens alone do not establish compliance.
## The SDS orange
The shared definition is [`css/colors.css`](../sylhet/css/colors.css). `--sds-orange-srgb: #f15c2b` is the universal fallback. `--sds-orange` adds `color(display-p3 0.945098 0.360784 0.168627)` only when both CSS support and the display's P3 gamut are available. These are intentional gamut variants, not numerically equivalent colors: the P3 variant keeps a vivid orange on wider displays. Use `var(--sds-accent)` for themed components and `var(--sds-orange)` for a fixed SDS identity swatch. Preserve the darker accent-text token for small text and focus.
The opening and closing scenes, square actions, word grid, live SVG Lotties, sound lab and orange layout previews share this definition. The retained WebGL renderer uses a gamut-mapped sRGB fallback through `js/color.js`; it cannot display colors beyond its drawing buffer. Standalone SVG posters and the favicon include the palette, and layout exports include `colors.css`. Supplied brand colors, green, and explicitly chosen place palettes remain independent.
Browsers apply their own display-profile and color-management settings. A screenshot alone cannot establish the exact configuration, and a website cannot guarantee identical physical color on every screen. Do not add browser sniffing, whole-page saturation filters, or require visitors to change browser flags. Compare color-managed browsers on the same calibrated display. CSS color-space reference: [MDN color()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/color); numeric renderer conversion: [MDN canvas colorSpace](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/colorSpace).
## Space
`--sds-space-*` suffixes follow quarter-rem units: `1=.25rem`, `2=.5rem`, `3=.75rem`, `4=1rem`, `6=1.5rem`, `8=2rem`, `12=3rem`, `16=4rem`, `24=6rem`, `32=8rem`. A `space-5` token is not shipped.
`--sds-width:1440px`; `--sds-gutter:clamp(20px,4vw,72px)`; `--sds-radius:8px`. Use `var(--sds-measure,65ch)` for reading measure and `var(--sds-section,clamp(64px,9vw,144px))` for vertical rhythm. Padding is included in the container's border-box width.
## Type and time
`--sds-font` declares Inter, Arial and sans-serif. `--sds-mono` declares Geist Mono then system monospace. Both fonts are bundled: `sds.css` self-hosts Inter and Geist Mono from `sylhet/fonts/` with `@font-face` rules, under the SIL Open Font License. No external font service is contacted. Keep the fallbacks in place for slow or failed loads.
| Token | Value | Role |
| --- | --- | --- |
| `--sds-text-xs` | `.75rem` | Fine print |
| `--sds-text-sm` | `.875rem` | Small text, compact controls |
| `--sds-text-md` | `1rem` | Body text |
| `--sds-text-lg` | `1.25rem` | Lead paragraph |
| `--sds-text-xl` | `1.5rem` | Small heading |
| `--sds-display-1` | `clamp(3.5rem,8.8vw,9rem)` | `h1` |
| `--sds-display-2` | `clamp(2.5rem,5.4vw,5.5rem)` | `h2` |
| `--sds-display-3` | `clamp(1.5rem,2.7vw,2.5rem)` | `h3` |
Paragraphs no longer have a global width limit. Use `.sds-prose` or `.sds-measure` to keep reading text at `--sds-measure`.
`--sds-duration:240ms` and `--sds-ease:cubic-bezier(.22,1,.36,1)` define short feedback. Animate only necessary properties. Still and reduced-motion rules take priority.
```css
.reading-page { --sds-width: 1200px; }
.reading-copy { max-inline-size: var(--sds-measure, 65ch); }
```
Keep overrides scoped and documented. Preserve semantic roles and verify every modified theme/state.
## Depth
| Token | Value | Role |
| --- | --- | --- |
| `--sds-z-base` | `0` | Normal flow |
| `--sds-z-sticky` | `100` | Sticky headers and bars |
| `--sds-z-overlay` | `1000` | Overlays and dialogs |
| `--sds-z-toast` | `1100` | Short notices above overlays |
| `--sds-shadow-1` | small, soft | Slight lift |
| `--sds-shadow-2` | medium | Raised panels |
| `--sds-shadow-3` | large | Overlays |
Shadows are stronger in the dark scheme. Do not use a shadow as the only boundary of a control.
## Optional place palettes
Load `sylhet/css/sds-places.css` **after** `sds.css` only when choosing a named alternative, then set `data-sds-theme` on `html`. The exact eight IDs, source values, dark variants, contrast-check scope and loading example are in [place palettes](place-palettes.md) and `sylhet/place-palettes.json`. The optional file changes only accent, accent-text and soft; it keeps neutral grounds and normal layout tokens. A named theme overrides the generic orange/green choice at that loading order. Remove `data-sds-theme` to return to the normal accent API.
Supplied brand colors take precedence. Treat the green-for-nature/community and orange-for-creative/maker guidance as starting heuristics, then review the actual context and contrast. City-inspired names are not evidence of historical palettes or cultural certification.
## Token source and exports
`tokens/sds.tokens.json` is the source of truth for token values. It uses the W3C Design Tokens Community Group format: groups such as `color`, `space` and `shadow`, and tokens with `$value`, `$type` and `$description`. Each token's custom property name is in `$extensions["studio.z7.sds"].css`. `$value` is the light value. A token that changes by mode lists every mode under `$extensions["studio.z7.sds"].modes`: `light`, `dark`, `green`, `green-dark`, `high-contrast` and `high-contrast-dark`. A token without modes is the same everywhere. The orange token keeps its Display P3 variant in `$extensions["studio.z7.sds"].p3`.
`sylhet/sds.css` stays the runtime stylesheet. Nothing is generated into it, and nothing about how pages look has changed. Two scripts work alongside it:
- `node scripts/build-tokens.mjs` reads the JSON and writes the files below into `sylhet/tokens/`. Run it after changing the JSON.
- `node scripts/check-tokens.mjs` checks that every token has `$value` and `$type`, that the light, dark, green and green-dark values match `sds.css` and `css/colors.css` exactly, and that text and boundary colors meet WCAG 2 contrast in all six modes. It prints a table and exits with an error on any drift or failure. Run it before releasing, and whenever `sds.css` or the JSON changes. If the two disagree, update whichever is wrong so they match again.
Both scripts share helpers in `scripts/tokens-lib.mjs` and need no packages.
Generated files in `sylhet/tokens/` (each says it is generated; do not edit them by hand):
| File | What it is |
| --- | --- |
| `sds-tokens.css` | Every `--sds-*` token in `@layer sds.tokens`, with the same mode selectors as `sds.css`. Use it only when you want the tokens without SDS base and component styles. Do not load it together with `sds.css`. |
| `sds-high-contrast.css` | The opt-in high-contrast mode, described below. |
| `tokens.json` | Flat, resolved values for each mode, keyed by custom property name. |
| `tokens.js` | ES module: `tokens` (resolved values per mode), `modes`, and `cssVar(name)`, which returns `var(--sds-…)` for `'paper'`, `'sds-paper'` or `'--sds-paper'`. |
| `tokens.d.ts` | TypeScript types for `tokens.js`. |
| `tailwind.css` | Tailwind CSS v4 `@theme inline` block mapping theme variables (for example `--color-sds-paper`) to `var(--sds-paper)`. Load `sds.css` as well. Z-index and duration have no Tailwind theme namespace and are left out. |
| `figma-variables.json` | One collection, `SDS`, with modes `Light` and `Dark`. Each variable has `name` (such as `color/paper`), `type` (`COLOR`, `FLOAT` or `STRING`), `cssVariable`, `description` and `values` per mode. Colors are `{ hex, r, g, b, a }` in 0 to 1; rem and px sizes are pixel numbers (1rem = 16px). It is a plain data file for import scripts or plugins, not a native Figma file. |
### High contrast (opt-in)
High contrast darkens secondary text and boundaries without changing grounds, accents or status colors. In light it sets `--sds-muted` to `#4a4d46` (8.2:1 on paper), `--sds-line` to `#6e7168` (4.7:1) and `--sds-border-strong` to `#5c5f57` (6.2:1). In dark it sets them to `#d2d6ca`, `#949a89` and `#a6ac9b`. Lines become real boundaries in this mode, not only decoration.
To use it, load the file after `sds.css`:
```html
```
`data-sds-contrast="more"` turns it on. Once the file is loaded, visitors whose system asks for more contrast (`prefers-contrast: more`) also get it, even without the attribute. It works with `data-sds-scheme="dark"` and `"auto"` and with the green accent. Pages that do not load the file are unaffected.
---
# Optional place palettes
SDS's main voice is neutral white and black with restrained green or orange. Eight optional combinations offer a different accent without changing the page ground, typography, spacing, or composition. Each has a plain color name; the place credited as its inspiration is a design association, not a historical palette or cultural certification.
| Choice | Direction | Accent fill | Accent text | Soft emphasis |
| --- | --- | --- | --- | --- |
| `forest` · inspired by Sylhet | Leaf green, deep forest text | `#7bae8b` | `#245c3d` | `#e7eee7` |
| `tea-leaf` · inspired by Srimangal | Lime and sage | `#bfdc4a` | `#42650d` | `#edf2df` |
| `indigo` · inspired by Kyoto | Quiet indigo | `#a9b4dc` | `#3b4c89` | `#eceef7` |
| `burnt-orange` · inspired by Lisbon | Warm orange | `#f45421` | `#b9310a` | `#fcebe2` |
| `slate` · inspired by Oslo | Cool blue grey | `#a7bec4` | `#3b5967` | `#eaf0f2` |
| `rose` · inspired by Jaipur | Muted rose | `#e7a6ad` | `#98434e` | `#f8e9eb` |
| `violet` · inspired by Seoul | Dusty violet | `#b8adc9` | `#64497e` | `#f0ecf5` |
| `ochre` · inspired by Marrakech | Soft ochre | `#d9ad69` | `#805318` | `#f5eddd` |
Forest, Tea Leaf and Burnt Orange stay within the green/orange signature family. The other choices are alternatives when the content or supplied identity calls for them. Use the fill sparingly and the darker text token for links, small emphasis or focus. A palette is not a new layout, and no choice is automatically activated.
## Load and choose
Load the optional stylesheet **after** the modern foundation. No edit to the main stylesheet is necessary.
```html
```
Adjust these paths to the actual deployment. Set the theme and scheme on the root `html` element. `data-sds-scheme="dark"` selects the lighter text accent and darker soft emphasis supplied by this file; the main stylesheet supplies the dark neutral grounds. The optional sheet itself changes only `--sds-accent`, `--sds-accent-text`, and `--sds-soft`.
With this loading order, a named theme overrides the generic `data-sds-accent` choice. Remove `data-sds-theme` to return to the normal orange or green accent API. Supplied brand colors still take precedence when appropriate; review their actual text/background contrast separately.
## Data and checks
`sylhet/place-palettes.json` is the machine-readable source for these shipped values. Its `themes` array contains `id`, `label`, `accent`, `text`, `soft`, `meaning`, `default`, `signature`, and `dark: {accent, text, soft}`. `default` is false for every optional theme. `signature` identifies a combination within the green/orange family; it does not activate the theme. `defaults.theme` is null.
`docs/research/palette-audit.json` records 80 calculated contrast pairs across the eight light/dark combinations. Accent text was checked against paper, surface and soft emphasis; main ink against soft emphasis; the unchanged near-black on-accent ink against every fill. All meet 4.5:1, with a minimum calculated ratio of 5.16:1. The soft fill itself is decorative and is not a control boundary.
This is a solid-color token audit. Check real pages, images, transparency, hover and focus states, any nested overrides, and user-supplied colors before release. Color must not be the only signal for an action or state. Preserve **Sylhet Design System · Z7 Studio · Mustafejur Rahman, Founder, Lead Director & Developer** attribution and the project license.
---
# Layout and composition
Begin with reading order. A sequence is an argument: context before evidence, prerequisites before installation, eligibility before application, or an object before dimensions. Color changes do not change that argument.
## Primitives and recipes
`.sds-container` centers a bounded page with gutters. `.sds-section` supplies vertical rhythm. `.sds-grid` has twelve equal columns with a four-column fallback at its narrow breakpoint. `.sds-stack` arranges vertical siblings and `.sds-cluster` wraps related controls or labels.
The catalogue describes **recipe-specific** grids: 12 columns at 64rem and above, 8 from 48rem to below 64rem, and one below 48rem. Implement these rules locally; they are not automatically produced by `.sds-grid`.
```css
.case-opening { display: grid; gap: var(--sds-space-8); }
.case-opening > * { min-inline-size: 0; }
@media (min-width: 48rem) {
.case-opening { grid-template-columns: repeat(8, minmax(0,1fr)); }
.case-opening__copy { grid-column: span 5; }
.case-opening__figure { grid-column: span 3; }
}
@media (min-width: 64rem) {
.case-opening { grid-template-columns: repeat(12,minmax(0,1fr)); }
.case-opening__copy { grid-column: span 7; }
.case-opening__figure { grid-column: span 5; }
}
```
Spans such as `[2,8,2]` describe spatial lanes including empty margins. Use grid placement for those margins; do not create empty landmark elements. `[7,5]` describes two information-bearing lanes. Read each section's purpose and element list to map content.
## Order and density
DOM order must match mobile reading and focus order. Do not visually move actions ahead of conditions while leaving keyboard order elsewhere. Use `minmax(0,1fr)`, wrapping labels, `min-inline-size:0` and bounded media to prevent page overflow.
Budgets are planning targets. If copy exceeds them, edit with the author, split the section or move reference detail to a dedicated page. Do not line-clamp essential text or set fixed text heights. Keep prose near 65 characters per line even when images span the page.
Make an index sticky only when it fits and does not obscure focus. Remove sticky behavior on narrow or short screens. Tables can scroll in a named region; the page should not require horizontal scrolling at 320px.
Select a recipe by task, copy, imagery and evidence. Avoid unsupported social proof or repeated decorative cards. See [schema](layout-schema.md) and [quality](quality.md).
---
# Typography and content
Use neutral sans typography, deliberate headings and a monospace utility voice. The modern CSS self-hosts Inter at 400, 500 and 700, with Geist Mono for utility text. Font files and OFL notices ship in `sylhet/fonts/`; preserve those notices. The default display voice is a consistent sans serif, using weight, scale and spacing rather than an automatic italic serif accent. Review fallback reflow and script coverage before changing a webfont.
| Role | Modern default | Content |
| --- | --- | --- |
| `h1` | `clamp(3.5rem,8.8vw,9rem)` | One page subject, usually 3–11 words |
| `h2` | `clamp(2.5rem,5.4vw,5.5rem)` | A meaningful section title |
| `h3` | `clamp(1.5rem,2.7vw,2.5rem)` | Subsection or independent article title |
| Body | `1rem/1.6`, paragraph limit 65ch | Specific, readable prose |
| `.sds-label` | 11px uppercase mono | Short, supplementary eyebrow |
| `.sds-badge` | 11px mono | Brief supplementary metadata |
Expressive heading defaults need local size overrides for documentation, dashboards and embedded panels. Choose levels for hierarchy, not visual size. Verify reflow at 200% text enlargement and high browser zoom without clipping. Small utility text should not carry long instructions or essential body copy.
## Write the interaction
Use destination nouns and operation verbs: “Read the guide”, “Download SVG”, “Save changes”. Avoid repeated “Learn more” links without context. Describe file format, size and license near downloads. Explain opening a different application when that would surprise the reader.
A persistent field label identifies the input; a placeholder is only an optional example. Errors name the problem and recovery: “Enter a date after 17 November” is better than “Invalid input”. Success text must reflect a confirmed result.
Avoid rigid ` ` tags that break narrow layouts. Review tight tracking in each font and script. Keep accent phrases rare, and prefer a single clear emphasis rather than several competing colors or faces.
## Multilingual pages
Set the correct document and passage `lang`. Use fonts that actually cover Bengali, Sylheti Nagri or other required scripts and support shaping. Do not assume Latin tracking, uppercase or character splitting transfers safely. Exclude complex-script text from glyph substitution until manually reviewed with appropriate readers and assistive technology.
Mark missing factual copy as an editorial placeholder. Never fill a beautiful layout with plausible but invented claims.
---
# Components and markup contracts
These are modern primitives in `sds.css` and `sds.js`. Styling is not a complete widget. Application state, server processing and advanced keyboard behavior require implementation.
## Actions
```html
Explore work
```
Use links with destinations for navigation and buttons for operations. Base actions have a 48px minimum height (46px at the narrow CSS breakpoint). Preserve focus indication; show pending text, true disabled state and recoverable errors when relevant. Copying, submission and network status are application code. Never nest controls inside linked cards.
The default (secondary) button and `.sds-field` use `--sds-border-strong`, which has at least 3:1 contrast against paper and surface in both schemes.
### Sizes
```html
```
`.sds-btn--sm` is 40px tall and `.sds-btn--lg` is 56px tall at every width. `.sds-btn--icon` makes a square button with no gap (48px, or 40px or 56px when combined with a size). An icon-only button needs an accessible name, such as `aria-label`, and its icon should be hidden from assistive technology.
### Danger
```html
```
Use `.sds-btn--danger` only for destructive or irreversible operations. Its label must say what will happen; color does not carry the warning on its own. Ask for confirmation in application code where the action cannot be undone.
### Busy and disabled states
```html
Next chapter
```
`aria-busy="true"` adds a small spinner after the label. The spinner does not rotate under reduced motion or `data-sds-motion="still"`. Change the visible text as well (for example "Sending") and remove the attribute when the operation ends. On an icon button the icon is hidden while busy.
`aria-disabled="true"` looks the same as `:disabled` and blocks pointer clicks, but it does not stop keyboard activation. Your script must ignore activation while it is set. For a link that should not go anywhere, remove its `href`. Prefer the native `disabled` attribute on buttons unless the control must stay focusable so people can find it.
## Surfaces
```html
Guide · 8 min
Choose a composition
Match reading order to the task and content you have.
Read the composition guide
```
`.sds-card` provides a border, ground, padding and radius. It does not make its whole surface interactive or supply selection state. Use a list for peer items and article for independent content. Badge text is supplementary, not a replacement for a state label. `.sds-muted`, `.sds-label` and `.sds-rule` add visual hierarchy without changing semantics.
## Status badges
```html
PublishedDraftOverdueNew
```
The four modifiers color the badge text with the matching `-text` token and the border with the matching fill. The word inside the badge must state the status; color only supports it.
## Alerts
```html
Route closed. The riverside path is flooded until Friday.
```
`.sds-alert` is a bordered callout with a 4px border on the inline-start side. Modifiers `--success`, `--warning`, `--danger` and `--info` change that border color. Text stays in the ink color. Start the message with a clear word such as "Error" or "Saved" so the meaning does not depend on color.
Content that is present when the page loads needs no ARIA role. Add `role="status"` (polite) or `role="alert"` (urgent) only when the alert content changes dynamically after load, for example after a submission result arrives. Put the role on a container that already exists in the page, then change its text. Do not use `role="alert"` for routine messages.
## Reading text
```html
Paragraphs, lists and links get comfortable spacing.
Inline code uses the mono font.
```
Paragraphs no longer have a global width limit. `.sds-prose` limits its width to `--sds-measure` (65ch), adds space between paragraphs and lists, underlines links and styles inline code. Use `.sds-measure` alone when you only need the width limit.
## Fields
```html
```
`/enquiries` is illustrative: implement the endpoint before publishing. `.sds-field` styles native fields; it does not validate, submit or save. Associate errors with `aria-describedby`; set `aria-invalid` after validation fails and preserve entered values. Announce confirmed asynchronous results with a polite live status. Field borders use `--sds-border-strong` for at least 3:1 non-text contrast against paper and surface. If you change field or page colors, check the boundary again.
## Navigation disclosure
`[data-sds-menu]` on a button uses `aria-controls` to find an element, toggles its `hidden` attribute and updates `aria-expanded`. Supply an explicit initial state. This simple disclosure does not implement modal focus trapping, Escape behavior or ARIA menu arrow keys. Ordinary navigation should use ordinary links. For no-JavaScript access, expose links initially and collapse them only after successful wiring.
## Glyph text and advanced patterns
`data-sds-float` opts text into slow gravity drift. The root preset `data-sds-text="gravity"` includes ordinary copy, navigation and CTA labels. Source words and hit targets stay in place; decorative grapheme copies return on leave or pointer release. `initGravityText` supplies stop/destroy lifecycle controls. The older `data-sds-glyphs` symbol substitution remains separate outside gravity mode. Fields, code, editing and essential status messages are excluded. Test real scripts and selection. Read [motion](motion.md) and [the showcase contract](expressive-motion.md).
`initSquareActions` gives `.sds-btn`, `.sds-scene-button`, retained `.btn` and custom `[data-sds-action]` square geometry and a theme-colored light after pointer/keyboard entry. Lighting persists only for the page visit and does not imply a pressed or successful state. Native focus remains visible.
Modern tabs, dialogs, comboboxes, sortable tables, uploads, authentication and chart behavior are not complete shipped widgets. Native `details` can serve a simple disclosure and native tables can represent data. Implement and document advanced keyboard models, focus, state and failure behavior explicitly. Legacy `sy-*` widgets have different contracts; they are not automatic `sds-*` aliases.
---
# Accessibility
Accessibility is a page behavior to verify, not a quality inherited by including a stylesheet. Aim for WCAG 2.2 AA and document the actual checks and gaps. The official [WCAG 2.2 standard](https://www.w3.org/TR/WCAG22/) is the normative reference; local law or procurement requirements may differ.
## Structure and operation
Use a descriptive document title, correct `lang`, one main landmark, named navigation and a visible-on-focus skip link. Preserve a logical heading outline with one page `h1`. Set link destinations and button types explicitly. Never use a clickable `div` when a native button suffices.
All controls must work by keyboard and touch. Focus remains visible, logical and unobscured by fixed navigation. Hover cannot be the sole way to reveal a caption, menu, instruction or action. A tooltip needs an accessible, dismissible interaction; a `title` attribute alone is insufficient for essential help.
Modal dialogs require a name, initial focus, contained focus where appropriate, Escape dismissal where appropriate, background handling and focus return. The modern SDS navigation toggle is a simple disclosure; it is not a modal implementation. Use a tested accessible primitive or implement the full contract before calling it a dialog.
## Perception
Verify text contrast on actual backgrounds: 4.5:1 for ordinary text and 3:1 for qualifying large text. Check non-text contrast where a boundary or state is necessary to identify a control. The light decorative `--sds-line` does not by itself establish a sufficiently contrasting form boundary. Do not communicate error, success, selection or availability through color alone.
Check zoom, text enlargement, text spacing and a 320px viewport without lost content or page-wide horizontal scrolling. Allow labeled data tables to scroll inside their own region. Respect the user's forced colors; do not suppress focus or rely exclusively on custom background images.
## Forms and updates
Use persistent labels. Explain unusual constraints before submission. Associate errors and help with inputs, preserve values after errors and provide a useful recovery action. Announce asynchronous outcomes in an appropriately scoped live region; do not repeatedly announce decorative changes. Move focus only when the task needs it, with a predictable destination.
Validation and submission are different events. A success animation or cue must follow confirmed completion, not merely syntactically valid input. Render server errors in text with enough context to retry safely.
## Alternatives
Meaningful images need contextual alt; decorative duplicates use empty alt. Complex charts need a readable explanation and access to exact data. Decorative Lottie is hidden from assistive technology; meaningful animation needs an equivalent explanation. Avoid persistent movement or provide pause/stop control. Honor `prefers-reduced-motion` and explicit still mode.
Audio is supplementary, off by default and controllable. Every audio event must have an equivalent visible state. Silence must leave the task complete. Media containing spoken information needs appropriate captions or transcripts.
## Verify
Use automated checks to find obvious failures, then manually test keyboard, focus, touch, reduced motion, zoom and a screen reader. Record browser, device and assistive technology versions and the paths tested. Passing an automated scan is partial evidence, not certification. See [quality gates](quality.md) for the release checklist.
---
# Images and asset direction
Use images when they show evidence, place, material, scale or a useful detail. Do not use unrelated photography to make a sparse content brief appear complete. A type-led composition is often the better choice when no appropriate image exists.
## Planning contract
For each image record its filename, purpose, source or owner, usage permission, target ratio, focal subject, alt treatment and expected display size. The layout catalogue's `image.ratio` is a planning ratio, not a substitute for intrinsic dimensions. A section marked `required` calls for meaningful media; choose a different section if no asset supports it.
| Ratio | Typical use | Review |
| --- | --- | --- |
| 21:9 or 16:9 | Place, broad scene, installation | Small-screen crop still explains the subject |
| 4:3 or 3:2 | Projects and editorial figures | Captions retain context |
| 3:4 or 4:5 | Objects and vertical studies | Full essential silhouette remains visible |
| 1:1 | Object indices or small specimens | Detail is legible at actual size |
Use `object-fit:contain` for charts, screenshots, code or diagrams where cropping removes information. Use `cover` only when a valid focal crop survives. Art-direct a mobile source when a wide crop cannot remain informative.
## Implementation
```html
Joint study, prototype 02. Photograph by the project author.
```
These paths illustrate a naming pattern; supply real files. Do not lazy-load a likely primary above-the-fold image. Set correct intrinsic dimensions to reserve layout space. Select responsive sizes from actual rendered widths, compress assets and inspect visual quality. Keep diagrams as SVG when appropriate, with useful names and no unsafe embedded scripts.
## Alt, captions and placeholders
Alt describes the information an image contributes in context. A caption can provide date, source or interpretation without simply repeating alt. Empty alt is appropriate when a decorative image duplicates nearby text. Never use a filename as meaningful alt.
Modern SDS does not automatically replace missing photographs with legacy heritage art. Provide a graceful application fallback or omit unsupported media. Mark unfinished placeholders visibly in review builds and remove them before publication. Legacy `data-sy-art` is a separate feature, not an `sds-*` API.
## Generated and third-party material
Label generated illustrative material where it could be mistaken for documentary evidence. Never synthesize client work, people, metrics or events and present them as real. Keep prompts, source references and edits in the asset record. Third-party photography, fonts, logos and animation files retain their own rights; the SDS license does not grant those rights.
---
# Motion and Lottie
Motion explains sequence, feedback or a meaningful spatial relationship. Begin still. Add the smallest useful movement and keep the content complete when animation does not run. The modern CSS has short interaction transitions, explicit still mode and reduced-motion overrides; small scenes are provided by `scenes.js`, while the optional expressive-page preset includes the existing scroll choreography. See [Recreate the SDS showcase](expressive-motion.md).
## Modern controls
`data-sds-motion="still"` removes modern animation and transitions. `prefers-reduced-motion:reduce` shortens/removes relevant CSS movement. Custom scripts must consult the preference themselves; a CSS rule cannot stop a JavaScript animation loop. Do not make a preloader, text reveal or scroll listener a prerequisite for accessing content.
Use approximately 120–240ms for small state feedback and up to about 480ms for an optional single entrance when it adds clarity. These are editorial guidelines, not extra exported duration tokens. Prefer opacity and modest transforms over layout-property animation, and verify actual rendering performance. Avoid auto-scrolling, parallax, large zooming, rapid flashing and essential information in a marquee.
## Cursor-local glyphs
The showcase now uses slow gravity words: set `data-sds-text="gravity"` on the root, or `data-sds-float` on one block. `initGravityText(scope, {automatic: true})` covers ordinary copy, navigation and CTA labels. Words keep natural shaping and stable hit targets; decorative copies drift slowly and return on leave or pointer release. It pauses for reduced/still motion, blur and hidden documents. Fields, code, editing and marked exclusions stay ordinary. Do not layer the older symbol effect below over gravity words. The exact counting intro, orange column wipe, square orbit, five Lottie panels and square actions are documented in [Recreate the SDS showcase](expressive-motion.md).
```html
Structure with character.
```
`sds.js` initializes short `[data-sds-glyphs]` blocks. Near a pointer, temporary glyphs overlay the original character position in one brief pass; the original readable text is restored. The burst does not repeat while the pointer remains. It uses the inherited theme accent and ink instead of unrelated rainbow colors. The module retains an accessible hidden text copy and marks visual copies `aria-hidden`. It skips touch pointers, honors still/reduced motion and stops activity when the document is hidden. It exposes `initGlyphs(scope)` for newly inserted content.
The effect is decorative. Do not place it on fields, code, long reading passages or essential status messages. Character splitting can affect text selection, translation, shaping and complex scripts; test those contexts or omit the effect. The ordinary text is the touch and reduced-motion version. Keep any transient color use small enough to remain subordinate to the chosen page accent.
## Semantic Lottie assets
The modern `sds.js` automatically initializes `[data-sds-lottie]`. It uses the bundled, MIT-licensed lottie-web runtime in `sylhet/vendor/`, without requiring the legacy runtime or adding page badges. Choose a real asset name from `sylhet/lottie/manifest.json`; its 208 entries describe semantic intent, use cases, placement, recommended triggers, performance, poster and provenance.
```html
```
Include the poster image in HTML so it remains visible without JavaScript. When JavaScript runs, the player also supplies a poster if absent and keeps it visible until the animation is ready. An unavailable runtime, manifest or JSON leaves the poster in place. Supply `aria-label` when the drawing conveys information; decorative drawings are hidden from assistive technology by default. Status text should also appear as ordinary accessible HTML.
`data-sds-play` accepts `loop`, `once`, `hover` or `click`; omit it to use the asset's manifest recommendation. Hover also responds to keyboard focus. It plays one pass per entry/focus session; focusing an already hovered drawing does not restart that pass. Controls can wrap the drawing in a real button/link, or use `[data-sds-lottie-host]` on its interactive ancestor. Use a check mark only after an action actually succeeds. A loading drawing must correspond to a real pending operation.
The player loads files when a drawing enters the viewport, pauses offscreen and suspends playback while the page is hidden. Across all instances, at most three animations play concurrently; explicit interaction takes priority over ambient loops. Both the OS reduced-motion preference and an inherited `data-sds-motion="still"` show complete static posters. Preference changes are observed live. In still/reduced-motion mode, the player does not download the runtime or animation JSON. Runtime fill and stroke slots follow the active ink, paper, accent and soft tokens. An explicit `--sds-motion-secondary` adds a second accent; otherwise signal uses the primary accent. Root accent/theme/scheme changes refresh visible instances. Call `refreshLottieTheme(scope)` after custom inline token changes. The standalone SVG poster retains the original SDS palette; runtime retinting does not alter the distributed poster file.
For persistent movement, provide a visible pause control that toggles `data-sds-motion="still"` on the containing section. Keep the control available to keyboard and assistive-technology users. Avoid putting essential information only inside the illustration.
For content inserted after page startup:
```js
import { initLottie } from './sylhet/sds.js';
initLottie(document.querySelector('#new-content'));
```
The catalogue's `lottieSlots` are placement recommendations, not asset IDs. Verify a name in the animation manifest. SDS's distributed drawings are original code-authored geometry; third-party LottieFiles examples are research references, documented separately in `docs/research/lottie-audit.md`. The vendored runtime's full notice is in `sylhet/vendor/lottie-light.LICENSE.md`.
## Review
Test pointer enter/leave, keyboard focus, touch, reduced motion, explicit still mode, document visibility changes and unavailable JavaScript. Verify no layout shift, hidden copy or essential hover-only information. An effect should be easy to remove without rewriting content or navigation.
---
# Sound
Sound is an optional layer of meaningful event feedback. Modern SDS begins silent, has no automatic hover listeners and does not persist global opt-in. A visitor chooses to enable sound or requests a specific preview. Every operation remains clear in visible text with sound off.
Design-system sound has prior art. Material 2 published sound principles and guidance for applying audio to interfaces; SDS does not claim to be the first sound-based design system. See [evidence](evidence.md).
## Modern API
The canonical module is `sylhet/js/sound.js`, re-exported through `sylhet/sds.js`.
```js
import { sound } from '/system/sylhet/sds.js';
const toggle = document.querySelector('#sound-toggle');
toggle.addEventListener('click', () => {
const on = sound.toggle();
toggle.setAttribute('aria-pressed', String(on));
toggle.textContent = on ? 'Sound on' : 'Sound off';
});
document.querySelector('#preview-sound').addEventListener('click', () => {
sound.preview('select');
});
```
Use a real button with an initial accessible state, for example ``. Label the preview button so its click clearly requests audio. A preview does not enable all subsequent interface sounds.
| Method/property | Contract |
| --- | --- |
| `enable()` | Unlock in a synchronous visitor gesture; returns enabled state |
| `disable()` | Disable, invalidate pending playback and stop active sources |
| `toggle()` | Enable/disable and return new state |
| `enabled`, `on` | Read-only current enabled state |
| `setPack(name)` / `pack` | Select/read one supported material |
| `setVolume(value)` / `volume` | Clamp/read volume in the 0–1 range |
| `play(cue)` | Promise of whether a sample began; requires enabled state |
| `preview(cue)` | One explicitly requested preview, even while globally off |
| `prepare(cues?)` | Gesture-only unlock and preload; resolves to readiness without playback or opt-in. Default cues: select, open, success |
| `stop()` | Stop active sources and invalidate pending playback without changing enabled state |
| `destroy()` | Disable, close context and remove its visibility listener |
`createSound({baseUrl,pack,volume})` creates a separate instance. Default pack is `paper`; volume is `0.22`; default asset location is relative to the module. Keep the directory structure or pass a URL ending in `/` when serving assets elsewhere. Destroy page-specific instances when a client-side view unmounts. Importing `sds.js` also initializes glyph/menu behavior; import the sound module directly when you only need audio.
## Packs and events
Five material packs are exposed: `paper`, `wood`, `water`, `glass` and `stone`. Supported semantic cues are `select`, `success`, `open`, `close`, `navigate`, `toggleOn`, `toggleOff`, `error`, `notify`. The modern module maps `select` to legacy `click` samples and `navigate` to `whoosh` samples. It intentionally does not expose the legacy hover cue as an automatic interaction.
Use success after confirmed completion, open/close for a meaningful changed panel, and select for a deliberate selection. Do not attach cues to every link, scroll position or pointer move. Error sound must remain gentle, supplementary and optional.
## Failure and concurrency
Missing manifest, missing samples, unsupported Web Audio or blocked decoding should leave the interface silent and usable. Playback checks hidden-document state, throttles rapid requests, limits concurrent active sources and discards stale loads. These protections reduce bursts; they do not guarantee exact timing over a network. Do not delay a visual result while waiting for audio. Previews and enabling should originate in visitor gestures to comply with browser playback policies.
The legacy `audio.js` has different cues, remembered opt-in, synthesis and ambient features. Do not assume those behaviors apply to the modern sound module. Inspect source and the sound manifest before documenting sample provenance or recording tools; a filename alone is not evidence of how audio was produced.
## A / B sound lab
The optional public lab compares the same finite three-stage visual interaction silently and with material cues. Its text always reports selection, opening and completion. This is a local demonstration: no form submission, persistence or real transaction is implied. Sound can make the boundaries between those events easier to hear; compare them yourself rather than treating this demo as evidence of a measured usability improvement.
```html
```
Importing `sound-lab.js` mounts existing empty `[data-sds-sound-lab]` containers once after DOM readiness. Each instance uses its own controller; the global `sound` instance stays off. The explicit **B · Preview with sound** click unlocks and preloads only that short comparison. **A · Play silently** runs the same visible steps without requesting audio. Changing the material never plays anything. Glass is the lab default; paper, wood, water and stone are also available. The lab starts at 18% output, multiplied by manifest cue gains, with a 0–30% slider. The standalone sound controller keeps its existing paper/22% defaults.
```js
import { createSoundLab, initSoundLabs } from '/system/sylhet/js/sound-lab.js';
// Existing mounts are returned, so repeated initialization is safe.
const labs = initSoundLabs(document.querySelector('#new-content'));
const lab = createSoundLab(document.querySelector('#custom-lab'), {
pack: 'glass', volume: 0.18,
// baseUrl: new URL('/audio/', location.href),
});
// Call from an explicit visitor preview gesture only:
document.querySelector('#custom-preview').addEventListener('click', () => lab.play(true));
// play(false) runs silently; stop() cancels the comparison.
// On a client-side view unmount:
lab.destroy();
```
`createSoundLab(element, options?)` returns `{play(withSound = false), stop(), destroy()}`. `play()` resolves to whether the visual sequence started, not whether audio was audible. `initSoundLabs(root = document)` includes the root itself when it matches and returns its controller array. Destroy restores the original container markup, removes listeners, clears all sequence timers and closes its audio context. Hosts must call it when removing a client-side view.
Preparation waits at most four seconds before continuing with a visibly labeled silent fallback; it never delays real application feedback. The comparison then runs for 2.6 seconds and stops its remaining audio. Stop, another request, hiding the page and destruction invalidate pending playback. No repeated animation, autoplay, hover cue, global opt-in or remembered permission is used. Reduced motion and `data-sds-motion="still"` retain static stage changes without spatial transitions. With JavaScript unavailable, an empty mount stays empty; keep essential explanatory copy outside it.
## Asset status
The working set is the existing 53 MP3 files, not newly generated assets. Existing generation scripts identify ElevenLabs, but prior provider history was not independently verified. On 17 November 2026 the connected generation service reported that free generations were busy: the attempted take did not start and nothing was charged. No retry was made in that turn, and no new content URL or audio download resulted. The current samples have not received a new critical listening/mastering review; see the [sound review](research/sound-review.md) for the attempt record and verification limits.
---
# Recreate the SDS showcase
The main website consumes the same public SDS code supplied to people and AI. Use the expressive starter for the complete page, or independent scenes for a smaller project. Preserve real content, navigation and a complete static page.
## Entry points
For ordinary sites, load `sylhet/sds.css` and the module `sylhet/sds.js`. For the expressive page, start with `recipes/expressive/index.html`, load `sylhet/vendor/expressive/layout.css` and `sylhet/css/scenes.css`, then load `sylhet/sds.js`. Keep `data-sds-expressive` on the root. Do not load two full CSS bases together.
The preset retains the supplied Leneroo layout, nav morph, hero cycle, traveling mark, photographic transition, connected cards, image stack, chapters, FAQ, outro and WebGL ending. New square actions, orbit carriers, gravity words, opening and motion panels are readable SDS modules. The original button DOM remains; `data-sds-action` replaces its compiled hover controller.
## Effects
| Effect | Public contract | Behavior |
| --- | --- | --- |
| Counted opening | `data-sds-opening` / `createOpening(element)` | 001–100 over 3600 ms, 450 ms hold, stepped orange exit; about 5.5 seconds total |
| Block wipe | `createBlockWipe(element)` | Twelve vertical columns; 900 ms each and 45 ms stagger |
| Word grid | `data-sds-word-grid` / `createWordGrid(element)` | Colorful word pixels, monochrome background; finite sequence and replay |
| Square orbit | `data-sds-square-orbit` / `createSquareOrbit(element)` | Upright squares follow four straight sides; 32-second circuit |
| Lottie studies | `data-sds-motion-panels` / `createMotionPanels(element)` | Five square panels, four drawings each; finite entrance and hover replay |
| Gravity words | `data-sds-float` / `initGravityText(scope, options)` | Slow letter drift; returns on leave or pointer release |
| Square actions | `initSquareActions(scope)` / `data-sds-action` | Square corners and an accent light that persists after pointer/keyboard entry |
| Closing | `data-sds-closing` / `createClosing(element)` | Short reveal and complete native-flow fallback |
| Content / media | `data-sds-reveal` / `data-sds-media` | Local entrance or at most 18 px of image travel |
These are browser-side progressive enhancements. `initScenes(scope)` discovers declarative scenes after DOM insertion. Scene controllers expose `stop`, `sync` and `destroy`; opening, wipe, grid and closing also expose `play`. The wipe exposes `reset`. Sound is separate and never starts with these effects.
## Counted opening
Copy the full markup from the atlas or expressive recipe. Keep `hidden` and `aria-hidden="true"`: the sequence is decorative, dismissible with Escape, and never required to read the page. The 20 px Geist Mono counter stays at the bottom-left, 34 px above the screen edge, with a thin progress line below. Its counter measures the timed introduction, not downloaded bytes. Do not claim network progress.
`data-sds-opening-count="3600"` sets the count duration, bounded to 2000–6000 ms. `data-sds-opening-hold="450"` sets the hold, bounded to 200–1500 ms. A recovery deadline is count + hold + 2400 ms. Stop cancels timers, frames and column animations. Replaying an active intro does not create another sequence.
The copy is “I know you’re using AI to code.” and “Let’s give it a point of view.” Both use Inter. Adapt the joke to the project. `--sds-opening-color` follows the primary accent; SDS uses orange. Its column exit follows the supplied local recording, which is excluded from distribution.
## Colorful words and square circuit
The grid shares the 3 × 5 alphabet in `js/word-grid-data.js`. Set `data-sds-words="SDS|SYLHET|DESIGN|CREATE|ART"` or five short project words. `data-sds-grid-labels` supplies tiny labels. Active pixels use primary accent and optional `--sds-motion-secondary`. Background shapes use paper and low-opacity ink only. `data-sds-grid-hold` defaults to 1800 ms, `data-sds-grid-duration` to 640 ms. Keep Replay study. Reduced motion shows the first word.
The expressive orbit keeps `.intro_logo-parent`, `.intro_logo`, `.intro-orbit_track` and `.intro-orbit_item`. Mark the parent `data-sds-square-orbit`. The controller wraps satellites in `.sds-orbit-carrier` so path movement cannot overwrite inner reveals. Custom markup may use `data-sds-orbit-item`. Pure `squarePerimeterPoint` and `SQUARE_ORBIT_PATH` share its geometry. `data-sds-orbit-duration="32000"` accepts 12000–90000 ms. Playback pauses offscreen; still mode keeps a complete square composition.
## Five Lottie studies
`sylhet/motion-panels.json` supplies the actual Form, Craft, Response, Nature and Rhythm groups: twenty distinct existing assets. Each `.sds-motion-panel` is square and a `data-sds-lottie-host`. Its drawings use `data-sds-play="hover"` and include static SVG posters in HTML.
`createMotionPanels` replays the first drawing in each card on first view. `replayLottie(element)` can queue a drawing still loading; `pauseLottie(scope)` stops a group. The shared budget remains three players. Hover/focus does not restart an already playing pass. Six grid columns arrange three cards above and two centered below. `--sds-panel-width` can override the width. Its default considers viewport height so headlines stay visible.
## Gravity words
For the showcase behavior:
```html
```
With that root setting, `initGlyphs()` delegates to gravity for ordinary copy and navigation. Or mark one block `data-sds-float` and load the normal SDS entry. Direct use is `initGravityText(document, {automatic: true})`. The expressive preset waits for retained text setup before binding.
Source words keep natural shaping and original hit targets. A shared decorative overlay draws grapheme copies from DOM ranges, including in clipped headings, buttons and the SDS nav wordmark. The ordinary source stays in the accessibility tree. Drift is eased and bounded: at most 42 px upward, 19.32 px sideways and 7 degrees. Small type moves less. Copies return and disappear after leave, pointer release, blur, reduced motion or motion-off. Idle copy has no frame loop.
Fields, editable content, code, long code-like tokens and `data-sds-no-float` areas are excluded. Test real languages and selection. The earlier `data-sds-glyphs` symbol substitution remains available outside gravity mode; never layer both effects over the same text.
## Square actions and ending
`.sds-btn` and `.sds-scene-button` have square corners. `initSquareActions` also supports retained `.btn` and custom `data-sds-action` controls. Accent lighting lasts for the page visit, without storage. It is decorative: no false `aria-pressed` or success state. Normal keyboard focus remains visible.
The expressive closing requires `.canvas`, `data-footer-trigger` and `.nav_outro`. Keep them from the recipe. The maintained preset ends the reveal plane after the photo section so it cannot cover the finale. Procedural artwork needs no video. Keep the semantic `sds-closing` fallback, real CTAs, Z7 Studio authorship and Designed through SDS badge.
Runtime SVG/Lottie paths resolve relative to `sylhet/vendor/expressive/`. The recipe and full kit are checked on isolated local servers. Local servers bind to 127.0.0.1; publication is separate.
Read the [reproduction prompt](../prompts/recreate-expressive-site.md), [native atlas](../recipes/motion-atlas.html) and [motion guidance](motion.md). Primary restraint references: [Carbon motion](https://www.carbondesignsystem.com/building-blocks/foundations/motion/overview) and [W3C interaction animation guidance](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html). A successful build is not an accessibility certification.
Utility navigation such as documentation topic links is marked `data-sds-no-float` to keep labels readable. Small expressive words use a gentler drift (about 3–4 px and two degrees); display text retains the larger bounded motion. Mobile stack notes and statistics wrap inside their columns, and the ending hides its underlying duplicate footer while the closing navigation panel is open. These adjustments ship in the public expressive stylesheet too.
---
# Reproduce the SDS expressive website
Give this prompt the complete SDS folder or expressive starter ZIP. Replace bracketed facts with real information.
```text
Build a responsive multipage personal/nonprofit website for [project] with Sylhet Design System. Read AGENTS.md, registry.json, docs/expressive-motion.md, relevant foundations and LICENSE.
Start from the expressive starter or recipes/expressive/index.html. Preserve required scene anatomy and runtime. Its thin bridge uses public initExpressivePage. Use actual SDS modules, not approximate rewrites or invented attributes. Keep markup, behavior, styling and data readable and separate.
Use near-white paper, near-black ink, generous spacing and Inter headings/body. Green or orange is the primary accent unless real brand materials say otherwise. SDS uses both sparingly. Geist Mono is for small labels; no automatic italic serif display accent. Use supplied Z7 Studio identity and Mustafejur Rahman authorship for SDS. On another project's demo, mark Z7 branding as provisional until real materials are supplied.
Use the shared SDS orange token for its own identity: --sds-orange falls back to #f15c2b and adds the documented vivid P3 version on supported wide-gamut screens. Components, SVG and Lotties use --sds-accent; keep dark accent-text for small type. Reuse sylhet/css/colors.css, and include it in isolated layout exports. Do not approximate the orange separately in each effect or apply a whole-page saturation filter.
Keep the noticeable counted opening: square SDS tiles, timed 001–100 over 3600 ms, 450 ms hold, and twelve orange columns exiting left to right with a stepped edge. Keep decorative hidden fallback, Escape, recovery deadline, reduced motion and explicit replay. Place the 20 px Geist Mono counter at bottom-left, 34 px above the viewport edge, with its one-pixel progress line below. Keep utility/documentation labels still and readable with data-sds-no-float. The counter is the introduction timeline, not claimed network progress. Use Inter for “I know you’re using AI to code.” and “Let’s give it a point of view.” Adapt copy when appropriate.
Use the real word-grid scene with SDS|SYLHET|DESIGN|CREATE|ART, or five short relevant words. Color belongs on the word-forming tiles: primary accent and optional --sds-motion-secondary. Background shapes are paper and low-opacity ink. Preserve tiny labels, finite playback, readable holds and Replay study.
Make the intro center square. Use data-sds-square-orbit and smaller square satellites following a square perimeter. Carriers own the path transform; inner nodes own reveals. Preserve the traveling mark, 32-second circuit, viewport pause and complete still presentation.
Replace photographic text pills with five square motion-study panels, four small Lotties each. Use sylhet/motion-panels.json and actual manifests. Include SVG posters and semantic purpose. Use data-sds-motion-panels, data-sds-motion-panel and data-sds-lottie-host. Keep three active players maximum, finite entrance and one hover/focus pass per session. Fit width to available height so headlines remain visible. Most other sections stay quiet.
Use square CTAs everywhere, including arrow blocks. SDS's square-action helper keeps the accent light after pointer or keyboard entry during the page visit. This is decoration, not false success or pressed state. Retained .btn markup uses data-sds-action, not its old compiled Button hover controller.
Use data-sds-text="gravity" for slow hovering words, including CTA labels and the SDS nav wordmark. Use initGravityText. Preserve natural source text, fixed hit targets, decorative copies and bounded movement. Letters return on leave or pointer release. Skip touch, reduced motion, fields, code, editing and essential status text. Never layer symbol scrambling over floating words.
Reuse working photo transitions, connected toolkit cards, image stacks, chapter interactions, FAQ and outro. Images should show meaningful architecture, industrial design, technology or material. Supply dimensions, crops and alt text. Label generated concepts; do not invent clients, metrics, testimonials or email addresses.
Preserve the complete closing: .canvas, data-footer-trigger, .nav_outro and semantic sds-closing fallback. Keep a next step and Designed through SDS badge. Procedural art must not rely on missing video. Build [page list] with real navigation. Other pages may use modern SDS base; never load two full bases on the expressive page.
Sound stays off until chosen. Use quiet SDS cues for meaningful feedback; a success cue requires actual success. Personal/nonprofit use follows LICENSE. Business use and website sales need written permission. Support uses the published channel at https://z7.studio.
Verify desktop, short screens and narrow mobile: counted intro, orange stepped exit, colorful word pixels, square circuit, five panels, square lit actions, floating text and return, keyboard use, closing, still/reduced motion, missing assets, no overflow and no console errors. Test from an isolated local server so hidden main-site paths cannot mask dependencies. Report actual checks and limits.
```
Include the optional local layout desk and twelve three-page website studies when a human builder needs them. Read docs/designer.md and docs/website-layouts.md; use the public designer.js, designer-model.js and shared preview CSS. Keep the FreeSite by Z7 alternative at https://freesite.z7.studio visible in the designer area. This is a link to a separate editor.
---
# Code and integration
The modern system is plain CSS and browser ES modules. Copying it requires no framework-specific wrapper. This is not an installed React component package or a complete application framework.
## Keep the source inspectable
```text
public/system/sylhet/
sds.css tokens, base and visual primitives
sds.js progressive initialization and exports
js/glyphs.js optional cursor-local symbol effect
js/gravity-text.js source-preserving floating words
js/square-actions.js square actions and persistent accent light
js/motion-geometry.js shared deterministic path/drift geometry
js/sound.js explicit opt-in audio instance/API
js/sds-lottie.js optional semantic animation with poster fallback
vendor/ self-hosted Lottie runtime and license notice
sounds/ manifest and material samples
src/
pages/ semantic page structure and routes
styles/ small scoped composition rules
features/ application state and network behavior
data/ real content and asset records
```
Keep repeated content in readable data structures, but do not abstract a single paragraph into a schema merely because it is possible. Name files and functions by their job. Prefer explicit state and event listeners over hidden global side effects or inline handlers.
## HTML first
Links navigate without JavaScript. Forms have real processing or a visible demo label. Content is visible before modules load. A menu should not hide all navigation before its controller is available. Avoid blanket `opacity:0` reveal states: a failed script must not erase a page.
For framework integration, serve the CSS and asset directory at stable public URLs. Import glyph behavior after the DOM is ready and call `initGlyphs(scope)` when new route content appears. The glyph module guards against wiring the same element twice. Treat it as DOM enhancement; do not run it during server rendering. The current module has no public glyph teardown API, so repeatedly mounting large dynamic effect blocks requires care or an application wrapper with lifecycle handling.
For audio-only use, import `createSound` or `sound` from `js/sound.js`. New instances have `destroy()` for cleanup. Never create a new audio context for every click. Keep enable/preview calls directly tied to the visitor's requested gesture.
`sds.js` also initializes `[data-sds-lottie]` through the exported `initLottie(scope)`. For newly inserted animation fragments, call that function after insertion. The player uses a bundled runtime, real manifest names, static posters, viewport/visibility gating and a shared playback budget. Include poster markup for no-JavaScript access and a visible pause mechanism for persistent movement. Read [motion](motion.md) for exact modes and limitations.
## Data and security boundaries
Render user content as text by default. Sanitize any explicitly allowed HTML using an appropriate maintained tool. Do not insert untrusted SVG, scripts or Lottie expressions without inspecting their capabilities and source. Avoid inline code that conflicts with a strict content security policy; self-host optional dependencies where required.
Form validation in a browser improves usability but does not replace server validation, authorization or abuse controls. Do not put secrets in client code or ask visitors to supply unnecessary personal information. The design system does not implement authentication, storage, payment handling or deployment.
## Version and compatibility
`package.json` declares the private `sylhet-design-system` project at version `1.0.0`, with modern module/style entry points. A local version is not evidence of a public package release. `registry.json` is the modern discovery contract; `data/legacy-registry.json` preserves legacy APIs. Pin copied revisions in project notes. Compare local customizations and rerun affected checks when updating. Test modern CSS against your application's browser policy; support for every historic browser is not established.
Use [quality gates](quality.md) to verify implementation. Report source validation separately from browser observations, assistive technology testing and asset provenance.
## Expressive motion
Import independent scenes from `js/scenes.js`, or start with the complete `recipes/expressive/index.html` and `initExpressivePage`. The showcase calls the same public preset; its retained transition bodies also ship in `vendor/expressive/`. That preset owns one page and requires the provided scene anatomy. It is not a multiple-instance widget. See [the motion contract](expressive-motion.md) and [reproduction prompt](../prompts/recreate-expressive-site.md).
---
# Build with AI
Give an assistant `AGENTS.md`, `llms.txt`, the relevant guide and real content. The goal is an understandable page with a clear reader task, not a maximal list of effects. A sufficient brief should lead directly to work; a compulsory style questionnaire is not part of the current workflow.
## A useful brief
```text
Build a nonprofit project page with Sylhet Design System.
Readers need to understand the project and volunteer for one Saturday session.
Use white, near-black and a restrained green accent. Calm motion, sound off.
We have: mission copy, three dated outcomes with sources, venue access notes,
two permitted landscape images and a real signup endpoint.
Choose a fitting layout from data/layouts.json and explain the choice briefly.
Use the modern sds.css/sds.js API. Keep content, styles and behavior readable.
Mark missing factual copy and perform the documented quality checks.
```
The assistant should infer routine defaults, preserve supplied colors and proceed. Ask only when a missing fact changes the result materially, such as an unknown legal name, absent processing endpoint or ambiguous primary task. Do not ask the user to configure every token.
If the user has not selected colors, green is a useful first choice for nature, community, learning or calm; orange for creative work, makers, warmth or expression. State the choice briefly and keep it restrained. A supplied brand identity takes precedence. Optional place palettes need the separate stylesheet and real IDs from `sylhet/place-palettes.json`; do not silently substitute one or turn palette selection into a questionnaire.
## Selection algorithm
1. Extract the reader task and available content types from the brief.
2. Filter recipes by `siteTypes` and `intent`; then compare required images, section budgets and use/avoid criteria.
3. Pick one recipe supported by real content. Keep the ID and a short rationale in the implementation notes.
4. Read every section's source order, spans, content elements and responsive rule. Apply local recipe CSS; JSON does not create components automatically.
5. Remove unsupported sections. Add a necessary access, consent or evidence section with a written reason.
6. Implement the baseline before adding optional motion, sound or Lottie.
7. Verify with the quality checklist and report evidence, limitations and outstanding content.
## Honest outputs
Never invent metrics, customer names, testimonials, awards, prices, email addresses, endorsements or sample provenance. Use a conspicuous editorial placeholder and list the source needed. A catalogue entry is a specification, not a finished HTML file. An optional Lottie slot is not an asset ID. A CSS class is not a complete interactive widget.
Do not claim that a build command proves responsive quality, a token contrast check proves all accessibility or a loaded sample proves it was made with a particular recording service. Inspect the source/API before producing copyable examples. Modern `sds-*` and legacy `sy-*` APIs are distinct.
## Reviewable code and handoff
Use semantic HTML, small scoped composition styles and named interaction functions. Keep content and assets in predictable locations. Preserve original source and license notices. Tell the user what changed, what was verified and what remains. Do not hide limitations behind “production ready”.
For business-oriented requests, check the user's permission under [LICENSE](../LICENSE). Personal/nonprofit use is permitted; selling websites or other business use requires written permission from Z7 Studio. Teams needing support can seek it through [z7.studio](https://z7.studio). No email address or permission approval is implied.
## Machine files
`llms.txt` indexes maintained documentation. `llms-full.txt` concatenates those guides for offline context. `registry.json` discovers modern implemented primitives, exports, guides, asset manifests and defaults. `data/layouts.json` is the complete layout selection source; `data/layouts.schema.json` defines its shape. `data/legacy-registry.json` preserves the older component/asset contract. These files do not constitute a running MCP service.
---
# Layout catalogue schema
`data/layouts.json` contains versioned composition specifications. `scripts/build-layout-catalog.mjs` is the authored source and deterministic generator. It also generates `docs/layout-catalog.md`. Edit the source, then regenerate; do not hand-edit the generated catalogue.
## Root
| Field | Meaning |
| --- | --- |
| `$schema` | Relative path to the JSON Schema |
| `schemaVersion` | Contract version, currently `1.0.0` |
| `attribution` | Studio, author, role and website |
| `counts` | Actual layouts, families and section types |
| `defaults` | Minimal palette, motion and sound policy |
| `breakpoints` | Recipe breakpoints, independent of the generic CSS grid |
| `layouts` | Array of 200 materialized recipe objects |
## Layout
Stable `id` values use `sds-{family}-{two-digit-number}`. `name` is human-readable; `slug` is a display convenience. Use IDs for references rather than assuming display names never change. `family` and `siteTypes` support broad filtering, but the important selection fields are `intent`, `useWhen`, `avoidWhen`, content budgets and actual available content.
`pageSequence` includes navigation, ordered section type keys and footer. `sections` materializes each content section in that exact order. Navigation/footer are shared page responsibilities, not section objects. Repeated section types get distinct IDs. `status:"specification"` and `implementation` make the deliverable boundary explicit.
`preview`, when present, is the relative path to a runnable HTML composition scaffold. These previews use explicitly labeled sample content and illustrative generated images. They implement the specified reading sequence and responsive spans, but are not finished websites, working business applications or individually accessibility-audited releases. Rebuild them with `node scripts/build-layout-previews.mjs` after regenerating catalogue data.
`recommendedBrief` is editorial guidance, not an object to paste into the legacy brief API. `palette` and the explanatory heritage value are deliberately plain-language recommendations. Only supported `data-sds-*` values belong in markup.
## Section
Each section has an ID, `type`, `title`, `purpose` and `elements`. `columns` gives grid counts and intended spans at desktop/tablet/mobile. Desktop spans sum to twelve. Tablet spans may exceed eight across the list and therefore wrap to a new row. Mobile spans are all one in source order. Centered types such as `[2,8,2]` include spatial margin lanes; create grid offsets rather than empty semantic elements.
`contentBudget` gives recommended words, heading length and item ranges. These are planning targets, not hard validation limits. The root layout budget totals section targets, not a claim about a rendered page's actual word count.
`image` defines ratio, requirement, fit, mobile crop and alt direction. The layout's `images` budget counts media-bearing section slots, not the exact number of images in a gallery; item ranges may require more actual files. A code/chart specimen may be rendered as native HTML/SVG rather than a bitmap. Do not invent a photograph where the content calls for a real specimen.
`motionSlots`, `soundSlots` and `lottieSlots` are optional opportunities. Empty sound slots mean no suggested cue. A Lottie slot defines placement/role/fallback, not a filename. Accessibility and quality gates must be checked in the actual implementation.
## Example selection
```js
const catalog = await fetch('/system/data/layouts.json').then(r => r.json());
const candidates = catalog.layouts.filter(layout =>
layout.siteTypes.includes('nonprofit') &&
layout.contentBudget.words < 1100
);
const chosen = candidates.find(layout => layout.id === 'sds-nonprofit-04');
// Read chosen.sections; compose semantic HTML and local responsive CSS.
// The data does not render a finished page by itself.
```
Serve `data/` at the path you actually use; the example assumes a copied `/system/data/` directory. Do not treat selected recipes as permission for business deployment. Read [LICENSE](../LICENSE).
## Validation scope
The generator rejects duplicate IDs, duplicate ordered page sequences, unknown section types and invalid desktop span totals, and expects exactly 200 recipes. The JSON Schema describes the shape. Neither check replaces visual, keyboard, screen-reader, image, audio or content review. See [quality](quality.md).
---
# Quality gates
A release claim must have evidence. Use this list for the actual pages and states changed. Do not describe unperformed checks as passing. Automated generation validates data structure; it does not establish visual quality, accessible interaction or asset permission.
## Before browser review
- Confirm the reader task, real copy, destinations and attribution. Remove invented claims and unfinished placeholders.
- Run `node scripts/build-layout-catalog.mjs` if layout source changed. It checks 200 unique IDs and section sequences, known section types and desktop span totals.
- Inspect imports and file paths. Verify referenced images, audio and animation files exist and have appropriate provenance.
- Check HTML structure, heading outline, labels, button types and link semantics.
- Ensure form endpoints and visible states reflect real behavior.
## Browser matrix
| Context | Verify |
| --- | --- |
| 1440px and 1024px | Composition, line lengths, image crops, focus visibility |
| 768px and 390px | Reflow, source order, usable controls, no clipped labels |
| 320px | No page-wide horizontal overflow or lost essential information |
| 200% text enlargement / high zoom | Reflow, controls and fixed content do not overlap |
| Keyboard only | Skip link, every control, meaningful focus order, return paths |
| Touch | No essential hover dependency; controls and spacing usable |
| Reduced motion and explicit still | Complete content, no required travel or glyph animation |
| Sound off/on/preview | Clear control, one-preview semantics, visible equivalent states |
| Hidden tab / rapid input | No burst of stale audio or runaway motion |
| Missing assets / slow network | Content remains usable and placeholders are honest |
| JavaScript unavailable | Core content, navigation and non-enhanced actions remain usable |
Check at least the browsers in the consuming project's support policy. Run an automated accessibility scan and a manual screen-reader pass on important journeys; record the versions and scope. Review contrast for text, controls, focus and status against their actual backgrounds. Check both selected color variants and schemes if they are exposed to visitors.
## Interaction states
Review default, hover, focus, pressed/selected, disabled, pending, success, error, empty and offline states where relevant. A CSS hover demo does not verify a keyboard interaction. A syntactically valid form is not a successful server operation. A selected card is not saved until storage confirms it.
## Performance and content
Inspect layout shift and responsiveness during real use. Reserve image space, send appropriate sizes and avoid loading a player or audio context before needed. Check console errors and network failures. Use performance measurements only with recorded device, browser, network and test conditions; no universal performance score is implied.
## Completion record
```text
Page/revision:
Recipe ID and adaptations:
Automated commands and results:
Browsers/viewport sizes observed:
Keyboard/screen reader scope:
Motion/audio failure cases observed:
Content and asset rights reviewed:
Remaining limitations:
```
Keep this record brief but concrete. “Looks good” or “fully accessible” without scope is not an adequate validation claim.
---
# Evidence and prior art
Reviewed on 17 November 2026. These official sources inform the documentation's structure and interaction guidance. They are references, not dependencies, copied implementations or endorsements. The observations below are deliberately narrower than a claim to have audited each entire system.
## Primer
[Primer's overview](https://primer.style/) organizes GitHub's design system into product UI and shared foundations including accessibility, icons and primitives. [Primer Primitives](https://primer.style/product/primitives/) documents CSS-variable tokens for color, sizing, spacing and typography, including theme data attributes. This supports separating semantic tokens from usage guidance and making a theme's implementation inspectable.
[Primer accessibility](https://primer.style/accessibility/) explicitly includes foundations, design guidance, component patterns, accessible messaging and tooling. SDS's documentation therefore treats accessibility as concrete interaction and content work, not a final generic paragraph. SDS does not claim Primer compatibility or equivalent implementation coverage.
## shadcn/ui
[The official introduction](https://ui.shadcn.com/docs) explains editable component code, composition, distribution, defaults and AI-readable source. Its documentation exposes setup, theming, component pages, registry material and an `llms.txt` route. SDS takes a practical lesson: publish readable source and explicit boundaries so humans and assistants can inspect the behavior they use. SDS's own JSON layout catalogue is not the shadcn registry protocol or a compatible CLI package.
## Sound already has design-system precedent
[Material 2: About sound](https://m2.material.io/design/sound/about-sound.html) documents informative, honest and reassuring sound, distinguishes UX sound from music and voice, and describes feedback associated with UI actions. The page now carries an explicit notice that Material 2 is no longer maintained. It is useful historical prior art, not a claim that this is current Material 3 guidance.
That primary-source evidence is sufficient to reject a claim that SDS is the first design system with sound. SDS's differentiator can be its restrained material vocabulary, explicit opt-in and integration with its own layout and motion language. This is a positioning judgment, not a historical first claim or an independent benchmark.
## Content and accessibility
[Carbon content foundations](https://carbondesignsystem.com/guidelines/content/overview/) treats purposeful interface wording, capitalization, terminology, numbers and accessible content as shared decisions. SDS uses the same general discipline of specific labels, recoverable errors and accurate states, without copying a proprietary voice or claiming compatibility.
[WCAG 2.2](https://www.w3.org/TR/WCAG22/) is the normative accessibility reference linked by these guides. SDS targets practical checks aligned with AA, while leaving actual conformance claims to a scoped assessment of the finished site.
## Deliverable boundaries
- There are 200 curated, machine-readable layout **specifications** with unique page sequences, not 200 fully built or browser-tested sites.
- Modern `sds.css/sds.js` has a smaller contract than the preserved legacy library. Read source for exact APIs; legacy inventory counts do not describe modern components.
- Library file presence, downloadable source and generation success are not evidence of a recording provider, animation creator, commercial permission or accessibility certification.
- No claim of “world's first”, universal browser support, certified accessibility or guaranteed performance is made.
When a source changes, update the observation and retrieval date together. Do not silently convert archival guidance into a present-day product promise.
---
# License, credit and support
The controlling terms are in [LICENSE](../LICENSE). This page explains the intended project policy and does not replace those terms.
You may study, adapt and publish the original material for personal and nonprofit work under that license. Preserve copyright/license notices and appropriate attribution. Published sites must visibly name Sylhet Design System and Z7 Studio with a link to [z7.studio](https://z7.studio). Documentation and redistributed source must credit **Mustafejur Rahman, Founder, Lead Director & Developer**.
Selling websites, templates, themes or derivative packs; paid client work; business websites, marketing, products and internal business tools; and other business use require prior written permission. An example recipe named “shop” or “studio” demonstrates composition and does not grant a commercial deployment license. Nonprofit status does not permit reselling the system.
Suggested visible credit:
```html
```
Suggested source/documentation credit:
```text
Sylhet Design System — Z7 Studio
Mustafejur Rahman, Founder, Lead Director & Developer
https://z7.studio
Used under the Sylhet Personal and Nonprofit License.
```
## Requesting permission or support
Small businesses and development teams facing financial constraints may seek support or permission through **[z7.studio](https://z7.studio)**. Describe the intended use, audience and needed help. The invitation is not automatic permission or a guarantee of assistance. No unverified mailbox is supplied.
## Third-party rights
This license covers only material owned by the licensors. External fonts, photos, libraries, marks and animation files keep their own terms. Keep their notices and provenance records. Do not assume the SDS license re-licenses those assets, or that a downloadable file is free for every use.
The project does not claim affiliation with Primer, GitHub, shadcn, Material, Google, IBM or other referenced systems. Their documentation informed comparisons and quality practices; it is not evidence of endorsement.
---
# Study the whole website
SDS supplies two complementary collections. The **200 page compositions** describe the anatomy of an individual page, including reading order, responsive spans and content budgets. The **12 whole-website studies** connect three pages with a shared identity, navigation, typography, image treatment and ending. They are illustrative learning material, not completed client websites.
Open **Layouts** in the showcase, `recipes/layouts.html`, or the no-JavaScript `website-previews/index.html`. Each study can be inspected at desktop, tablet and phone sizes, opened as a full page, or loaded into the layout desk.
| Website study | Structure to study |
| --- | --- |
| Considered spaces | Split architectural opening, project rows and a generous story |
| An evolving practice | Image-led cover, project grid and statements |
| A shared place | Centered invitation, useful features and activities |
| A common purpose | Mission, context, image and clear process |
| An independent journal | Editorial opening, reading index and quiet story pages |
| Questions and observations | Research index, questions and evidence structure |
| A gathering of ideas | Centered event invitation and ordered programme |
| One useful step | Learning introduction, features and course progression |
| Small thoughtful tools | Editorial developer portfolio, projects and practice |
| Frames and places | Photography cover, image sequences and an about page |
| Everyday reconsidered | Object study, product imagery and material details |
| A useful place to begin | Resource index, service explanation and next steps |
Study the sequence before the decoration. Ask what the visitor needs first, what belongs together, where an image changes the pace, how much copy each section can hold, and what each page helps the next page explain. A good layout depends on real content; replacing a color is not a new composition.
All 36 pages are generated by `scripts/build-website-studies.mjs` using the public `designer-model.js` renderer and `designer-preview.css`. Their editable source lives in `data/website-layouts.json` (schema version 1.0.0). Each plan links to related composition IDs in `data/layouts.json`. The twelve studies have different section/variant sequences. Their sample text, images and static features are explicit; there are no fabricated customers, metrics or working forms.
The sample images are the six original AI-generated SDS design studies. Replace them with permitted project media. Whole-website studies share Inter, a near-white ground, near-black ink and one green/orange accent. Responsive rules are container-based so the same composition works inside the desk and as a standalone website.
Structural checks validate all 36 pages, one `h1` per page, linked navigation and local assets. Representative structures are reviewed in a browser; this does not mean every combination or device is individually audited. Read `docs/quality.md` before publishing. Personal/nonprofit licensing applies; business examples do not grant commercial rights.
---
# The SDS layout desk
The layout desk is a small local website designer for people who prefer to arrange a page before writing code. It also produces a precise brief for an AI coding agent. Open **Designer** in the showcase, or serve `recipes/designer.html` from the SDS bundle. No account, remote API, subscription or upload is needed for this local tool.
## Make a website
1. Study a complete website in **Layouts**. Open its Home, Work/Read/Learn and About pages. Compare desktop, tablet and phone. Choose **Use in designer**.
2. Select a page. Drag a part onto the canvas or press its **Add** button. Navigation, hero, text, image, projects, features, process, statement, resources, call to action, button and footer are available.
3. Select a part to edit its words, image study and available layout variants. Project name controls the provisional identity. Green and orange remain restrained accents.
4. Reorder with drag, **Move up/down**, or Alt + Up/Down on a focused part. Enter or Space selects a focused canvas section. Undo restores the last edit. Add or remove pages as needed.
5. Preview at 1280, 768 and 390 CSS pixels. These views scale within the desk. A phone can inspect a desktop composition without causing page overflow. The exported page responds to its actual viewport.
6. **Save layout** downloads editable JSON. **Import layout** restores a saved draft. **Copy AI brief** includes every page, part, variant and property. If clipboard access is unavailable, a text file is offered.
7. **Export website** downloads a ZIP containing linked HTML pages, CSS, local fonts and images, the editable JSON, exact AI brief, license, and a dependency-free local server. Run `npm run dev` in the extracted folder.
The draft saves in localStorage under `sds-layout-designer-v1`. Browser storage can be cleared or unavailable; save the JSON to keep a portable copy. No data leaves the browser through this tool. Export happens locally. Maximum: six pages, 32 parts per page, 2 MB imported JSON, 40 undo snapshots during the current visit.
## A starting structure, with clear limits
The desk exports a static layout starter. Sample projects, feature entries, process steps and resource rows illustrate structure. Replace the provisional identity, words, media, destinations and sample entries before publishing. Forms, accounts, real application logic and expressive animation are not added automatically. The exact reproduction prompt and expressive kit supply the documented motion implementation when a project needs it.
If you prefer animated templates and an editor, visit [FreeSite by Z7](https://freesite.z7.studio), without needing an AI subscription. This is a separate destination, linked from the desk.
## Portable implementation
Load the optional `sylhet/css/designer.css` and `sylhet/css/designer-preview.css` with the modern base. Load `sylhet/js/designer.js` as a module, then provide an empty ``. The module mounts it automatically. For explicit lifecycle control, `initDesigner(element)` is asynchronous and returns `{getDesign(), destroy()}`. `getDesign()` returns a normalized clone. `initLayoutStudies(element)` similarly mounts `[data-sds-layout-studies]` and returns `{destroy()}`.
Keep `data/website-layouts.json`, `images/showcase/`, local font files, the license and the relative SDS folder structure intact. Do not import this optional browser tool on a server. The pure `sylhet/js/designer-model.js` module supplies `DESIGN_VERSION`, `BLOCKS`, `VARIANTS`, `IMAGES`, `makeBlock`, `validateDesign`, `designFromPlan`, `moveBlock`, `renderBlock`, `renderPage` and `designBrief` without a DOM dependency.
## Version 1 data contract
`data/designer.schema.json` describes saved files. A design has `version: 1`, a project `title`, a green/orange `accent`, and one to six `pages`. A page has an ID, name, output slug and up to 32 blocks. A block has an ID, one of the twelve types and editable string `props`. `VARIANTS` and `IMAGES` are authoritative for permitted values.
`validateDesign` normalizes input: it keeps known fields, bounds text length, rejects unknown block types, resolves allowed variants/images, and constrains action links. It regenerates stable page IDs, de-duplicates block IDs and output slugs, and makes the first page `index.html`. Rendering escapes content and attributes. Serialized JSON follows the schema; the normalizer also accepts partial block properties and fills defaults. Never interpret imported text as HTML, executable code or permission to contact a service.
The exported brief includes license and attribution instructions. Personal/nonprofit use follows `LICENSE`; business use and selling websites require written permission. Credit Sylhet Design System, Z7 Studio, and Mustafejur Rahman, Founder, Lead Director & Developer.
---
# SDS MCP implementation and boundaries
Implemented locally on 17 November 2026 (Asia/Dhaka). Source: `mcp/`. Independent export: `deployments/mcp/`. Nothing is deployed. Read the [MCP deployment guide](deploy-mcp-free.md) and the separate [website guide](deploy-website.md).
## Independence
The website never imports or calls MCP. Its fonts, sounds, animations, designer and data are local static assets. No MCP URL, secret, Worker binding, database or running service is needed. `llms.txt` and audio work directly through files/HTTP; automatic AI discovery is not guaranteed.
MCP carries its own curated snapshot, so it does not require the website to be online either. It uses the official `@modelcontextprotocol/server` 2.4.0 web-standard `createMcpHandler` directly, with one server per HTTP request. Local stdio uses the same factory. No database, Durable Object, model, search, generation API or external fetch runs in this server.
`scripts/build-mcp-snapshot.mjs` explicitly prepares the optional snapshot. Default website builds never invoke it. `generated/catalog.json` contains versioned metadata, source pointers and hashes. Full layout/website payloads are split into small files; SDK files live in `public/sds/`. Hidden/raw folders, legacy docs and screenshots are excluded.
## Implemented interface
Eight tools:
- `sds_search`: metadata ranking, kind filter, 1–30 results and bounded query/version-bound cursors.
- `sds_get_layout`: one complete composition and responsive/content guidance.
- `sds_get_website_plan`: one complete linked three-page study.
- `sds_recommend_layouts`: deterministic matching with evidence terms; no second AI.
- `sds_get_asset`: real Lottie/icon/sound metadata, hash, copy path, poster and public URL where appropriate.
- `sds_get_api`: exact token, selector, attribute, export or behavior.
- `sds_get_guide`: maintained documentation chunks.
- `sds_read_source`: exact packaged HTML/CSS/JS/JSON/SVG/Markdown, with pagination.
Seven fixed resources cover start, version, registry, license, designer schema and indexes. Nine URI templates resolve exact catalog records and source chunks. Two prompts guide building and review. Results retain version, attribution, personal/nonprofit licensing and sound-consent guidance.
Catalog: 200 page recipes; 12 whole websites/36 pages; 208 Lotties; 257 icons; 53 sound assets. Designer schema version 1 allows 1–6 pages, up to 32 parts/page and twelve types. MCP supplies source/schema context; it does not edit, execute, export or publish a design.
## Boundaries
Remote access starts disabled and in token mode. Public mode must be explicit. Private mode uses a personal bearer secret and is not OAuth. Host/Origin validation and the same gate cover MCP and assets. Callers cannot choose arbitrary filesystem paths, URLs or network destinations. Local reads enforce resolved-path containment; errors do not disclose authoring paths or secrets.
POST bodies are limited to 64 KiB; source chunks to 18,000 UTF-16 characters; tool output to 32 KiB. Search is paginated, immutable indexes are shared, source cache has 32 entries, and audio is never played by MCP. Clients should copy needed SDK assets into finished websites so those sites have no MCP runtime dependency.
Current 2026-07-28 and stateless legacy ordinary tools/resources/prompts are supported. OAuth, sessions/replay, pushed sampling, model inference, audio generation and streaming subscriptions are not provided.
## Verification and hosting limit
Ten tests check snapshot hashes, payloads, ranking/cursors, aliases, source bounds, actual stdio clients, resources/prompts, access gates and HTTP bounds. Real HTTP SDK clients passed legacy and modern checks against the exact Worker handler through Node. Wrangler's deploy dry run builds the bundle.
Windows Application Control blocked local `workerd.exe`. This delivery does not claim a workerd run, live Cloudflare deployment or Cloudflare CPU measurement. Node is an additional local adapter, not a policy bypass.
Workers Free has finite quotas. `run_worker_first` gates assets, so those reads also count as Worker requests. See the deployment guide for current limits and the distinction between hosting, domains, client/model use and new sound generation.
Sound files are also available through authenticated MCP resources: sds://audio/{encoded-id}/{byte-offset}. Tool metadata supplies the first URI. Each read returns at most 64 KiB of base64 bytes and a nextUri; concatenate decoded chunks and verify the supplied SHA-256. This is a client-controlled download, never playback. It works in private mode without exposing a token to website code.
---
# Deploy the independent SDS MCP for free
Checked 17 November 2026 (Asia/Dhaka). The MCP is implemented locally in `mcp/`. Its independent release copy is `deployments/mcp/`, also supplied as `deployments/sds-mcp.zip`. Nothing has been uploaded or deployed.
## Keep the website independent
The website and MCP use separate repositories and deployment steps. The Vercel website does not need a Worker, MCP URL, secret, database, model API or running MCP process. It retains its own fonts, sounds, Lotties, layouts, designer and AI text files. You may never release MCP and the website still works.
The MCP also bundles its own curated SDS snapshot. It does not require the website to be online. Finished user websites should copy the required SDS files; they should not depend on an MCP connection or use this endpoint as their production CDN.
## Choose how far to release
| Choice | Runs where | Public exposure |
| --- | --- | --- |
| Local stdio | Your AI client launches Node | None |
| Local HTTP | Node on 127.0.0.1:8787 | This computer only |
| Private remote | Cloudflare Worker, personal bearer token | Token required for MCP and assets |
| Public remote | Cloudflare Worker, explicit public mode | Anyone can read the licensed snapshot |
Local modes need no hosting service. Remote modes use Workers Free within its limits. The endpoint supplies SDS data, not an AI model.
## Free hosting boundaries
This package uses no database, Durable Object, paid model, paid search, audio-generation API or external fetch. Cloudflare currently documents **100,000 Worker requests/day** and **10 ms CPU per HTTP invocation** on Workers Free. Its uncompressed Worker limit is 64 MiB. A `workers.dev` hostname avoids buying another domain. Check current [pricing](https://developers.cloudflare.com/workers/platform/pricing/), [limits](https://developers.cloudflare.com/workers/platform/limits/) and [workers.dev guidance](https://developers.cloudflare.com/workers/configuration/routing/workers-dev/).
For this package, `assets.run_worker_first` is `true` so the release switch and token gate cover every static asset. **MCP calls and bundled asset requests both invoke the Worker and count toward the request allowance.** Cloudflare's unlimited/free static-asset bypass pricing is not a claim about this guarded configuration. Copy assets to the finished website so visitor traffic does not consume MCP quota.
Remain on Workers Free for this zero-hosting-bill path. Do not upgrade or enable paid services unless you separately choose them. Free quotas can stop requests; there is no unlimited-traffic or uptime promise. Monitor CPU and errors after deployment. Local Node timings cannot prove Cloudflare CPU usage. Your AI client, new ElevenLabs generation and registered domain can have separate charges.
## 1. Install and check the standalone package
Use Node.js **22.12+** (Node 24 recommended), npm and Git. Extract the MCP ZIP, or open the independent export:
```powershell
Set-Location 'C:\path\to\deployments\mcp'
npm ci
npm run check
npm run build
```
Keep `src/`, `scripts/`, `test/`, `generated/`, `public/`, `wrangler.jsonc`, `package.json`, lockfile and notices together. No original parent/sibling folders are required. The packages are pinned. `build` runs `wrangler deploy --dry-run` and does not publish.
## 2. Test locally without an account
Run `npm run dev:node`. In a second terminal in the same folder, run `npm run check:http`. This exercises actual legacy and modern MCP clients, plans, source, sound metadata, schema, tools, resources and prompts. The listener binds to **127.0.0.1**, not the LAN. Stop it with Ctrl+C.
`npm run dev` uses Cloudflare's local `workerd` runtime instead. On this computer, Windows Application Control blocked `workerd.exe`. The same handler passed real HTTP tests through Node and the Cloudflare bundle dry run passed. Do not disable security policy. Use Node locally, or an authorized machine for a full workerd run. This delivery does not claim a live Cloudflare test.
For local stdio, configure the AI client's documented command fields:
```text
Command: node
Arguments: C:\full\path\to\deployments\mcp\src\stdio.mjs
Transport: stdio
```
The client launches and owns the process. Do not start it separately, and do not use `npm start` as the client command: npm's banner can corrupt protocol stdout. No token or public URL is needed.
## 3. Optional separate GitHub repository
Create a new empty **private** GitHub repository, for example `sylhet-design-system-mcp`. Do not pre-add a README/license. Push only this package, not the full authoring workspace:
```powershell
git init -b main
git add --all
git status --short
git commit -m "Add independent SDS MCP"
git remote add origin https://github.com/YOUR_GITHUB_USERNAME/sylhet-design-system-mcp.git
git push -u origin main
```
Review `git status` before committing. The included ignore file excludes dependencies, logs, `.wrangler`, `.build`, `.dev.vars` and `.env`. Keep tokens out of Git and remote URLs. Use Git Credential Manager or GitHub CLI. A private repository does not make a public-mode endpoint private. [GitHub guide](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github).
GitHub is optional for Wrangler CLI deployment. No workflow auto-publishes this package on a push.
## 4. Log in to Cloudflare when you choose to deploy
In the MCP folder:
```powershell
npx wrangler login
npx wrangler whoami
```
Complete browser login yourself and confirm the account. Choose Workers Free. Claim a `workers.dev` subdomain if prompted. Do not accept a paid upgrade for this path. [Wrangler commands](https://developers.cloudflare.com/workers/wrangler/commands/).
## 5. Explicitly select private or public mode
The supplied `wrangler.jsonc` starts with `SDS_REMOTE_ENABLED: "false"` and `SDS_ACCESS_MODE: "token"`. If uploaded unchanged, `/health` responds but MCP and assets return 503. There is no silent public release.
For **private personal access**, edit these two `vars`:
```json
"SDS_REMOTE_ENABLED": "true",
"SDS_ACCESS_MODE": "token"
```
Create a random URL-safe token in a password manager: use 64 letters/numbers or hex characters (32–512 characters are accepted). Save it there. Set it through Wrangler's interactive secret prompt:
```powershell
npx wrangler secret put SDS_BEARER_TOKEN
```
Paste the token only into that prompt. Never place it in a command argument, URL, screenshot or Git file. Clients must send `Authorization: Bearer YOUR_TOKEN` using a secure token/header field. The snapshot assets use the same gate. Private tool results omit public asset URLs. Sound metadata supplies an audioResourceUri for authenticated MCP downloads in 64 KiB chunks, with nextUri and SHA-256. Your MCP client can save decoded bytes without putting a secret into website code. No playback occurs.
This is a personal shared-token gate, **not an OAuth authorization server**. It has no per-user account/revocation flow. Choose a client supporting custom Authorization headers. A client that requires OAuth needs a separate OAuth integration; this package does not claim one.
For an intentionally **public SDS library**, edit:
```json
"SDS_REMOTE_ENABLED": "true",
"SDS_ACCESS_MODE": "public"
```
No token is required. Anyone can read the bundled licensed snapshot and eight read-only tools. Review `public/` before release. Hidden raw sources, local drafts, environment files, authoring folders and logs are excluded. The public endpoint grants no additional usage rights. The current MCP specification recommends authentication; this explicit mode is appropriate only for deliberately public, read-only content.
Native MCP clients normally omit Origin, which is accepted. Browser clients require their exact origin in `SDS_ALLOWED_ORIGINS` (comma-separated, including scheme/port); the endpoint's own origin is already accepted. CORS is not authentication. Custom domains also need their exact hostname(s) in `SDS_ALLOWED_HOSTS`. Do not use wildcard origins or put a private token into a public webpage.
## 6. Upload and verify
After reviewing the configuration and public snapshot:
```powershell
npm run check
npm run build
npm run deploy
```
**The last command uploads/releases the Worker and snapshot.** Wrangler prints the actual URL. Use the exact URL, for example `https://YOUR_WORKER.YOUR_ACCOUNT.workers.dev`, followed by **`/mcp`** for your AI client. `/health` is a simple status endpoint. Opening `/mcp` as an ordinary browser GET is not an MCP test; a 405 can be normal for the legacy stateless transport.
For a public endpoint, run:
```powershell
node scripts/check-http.mjs 'https://YOUR_WORKER.YOUR_ACCOUNT.workers.dev/mcp'
```
For private mode, test through the AI client's secure Authorization field. The test script can also read `SDS_TEST_TOKEN` from its process environment. Load it securely from a password manager and remove it after testing; do not type a literal secret into shell history.
Connect a compatible AI client using **Streamable HTTP** and the exact `/mcp` URL. Try: “Use SDS to recommend a personal portfolio layout. Read the plan, motion guide and actual code before implementing it. Keep the website independent of MCP.”
The server supports MCP 2026-07-28 and the SDK's stateless legacy lane for ordinary tools/resources/prompts. It does not run a model, generate audio, edit designs or implement session replay, pushed sampling, OAuth or streaming subscriptions. Model fees belong to the client/provider.
Verify a complete layout, whole-website plan, designer schema, Lottie poster/JSON, sound metadata, source chunk and prompt. Verify the chosen access mode. Check Cloudflare's CPU, requests and error charts before promoting the endpoint. No live deployment or Cloudflare CPU measurement was performed locally.
## 7. Optional custom domain
The free `workers.dev` URL is enough. For an existing Cloudflare-managed domain, open Worker → Settings → Domains & Routes → Add → Custom Domain. Use an unused subdomain such as `mcp.YOUR_DOMAIN`. **Do not replace the website's Vercel DNS records.** Cloudflare manages the Worker route/certificate. Add the MCP hostname to `SDS_ALLOWED_HOSTS`, redeploy and retest. [Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/).
Your website can stay on Vercel with Cloudflare DNS. It needs no MCP URL or configuration change.
## Updates, shutdown, and never releasing
From the authoring workspace, refresh the snapshot with `npm run mcp:prepare`, check it, then run `npm run release:mcp`. Review the new package before pushing/deploying. Export preserves Git metadata and local secret files; generated configuration returns to safe defaults, so review access mode before each release.
Disable remote access by setting `SDS_REMOTE_ENABLED` back to `"false"` and redeploying, or remove the Worker in Cloudflare. Remove custom routes/preview URLs you created if retiring it. Rotate a private token by replacing the Worker secret and updating clients. None of this affects the website. You can also never deploy MCP and keep using stdio.
## Primary references
- [SDK web-standard serving](https://ts.sdk.modelcontextprotocol.io/v2/serving/web-standard.html): direct factory, Host/Origin and auth boundary.
- [SDK stdio](https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-server.html): Node command and protocol stdout.
- [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28): protocol contract.
- [Worker asset routing](https://developers.cloudflare.com/workers/static-assets/routing/worker-script/): `run_worker_first`.
- [Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/) and [limits](https://developers.cloudflare.com/workers/platform/limits/): finite free allowance.
Preserve LICENSE and third-party notices. Credit Sylhet Design System · Z7 Studio · Mustafejur Rahman, Founder, Lead Director & Developer. Personal/nonprofit use only; business use and selling websites need written permission.
---
Sylhet Design System — Personal and Nonprofit License 1.0
Copyright (c) 2026 Z7 Studio and Mustafejur Rahman.
All rights reserved except as expressly granted below.
Author: Mustafejur Rahman, Founder, Lead Director & Developer, Z7 Studio.
Permission and support: https://z7.studio
1. GRANT
You may use, copy, study, and modify the original Sylhet Design System
source, documentation and original assets for your own personal projects,
learning, and nonprofit activities. You may publish resulting personal or
nonprofit websites and share modified source under this same license, provided
the notices and attribution required below remain intact.
2. BUSINESS USE REQUIRES PRIOR WRITTEN PERMISSION
This grant does not permit selling websites, templates, themes, components,
asset packs, or derivative design systems; paid or commercial client work;
use in a business's website, product, service, marketing, or internal business
tools; or other business use. Such use requires prior written permission from
Z7 Studio. Business-oriented recipes and demonstrations do not grant business
deployment rights. Nonprofit status does not authorize resale of Sylhet.
3. ATTRIBUTION AND NOTICES
Keep this license and source copyright notices with copies and derivatives.
Published websites must include a reasonably visible attribution naming
Sylhet Design System and Z7 Studio, linking to https://z7.studio.
Documentation and redistributed source must credit Mustafejur Rahman,
Founder, Lead Director & Developer. Do not imply author endorsement.
Preserve original provenance records and third-party notices.
4. SUPPORT REQUESTS
Small businesses and development teams facing financial constraints may seek
permission or support through https://z7.studio. This invitation does not
automatically grant permission, guarantee assistance, or change this license.
5. THIRD-PARTY MATERIAL
This license covers only material owned by the licensors. Third-party fonts,
libraries, photographs, animation assets, logos and other material remain
subject to their own licenses and rights. Follow accompanying notices.
No trademark rights are granted. Unclear provenance is not permission.
6. NO OTHER RIGHTS
Rights not expressly granted are reserved. You may not relicense original
Sylhet material under terms that remove these restrictions. A separately
agreed written permission may grant additional rights for its stated scope.
7. WARRANTY AND LIABILITY
THE MATERIAL IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE AUTHORS AND
COPYRIGHT HOLDERS ARE NOT LIABLE FOR CLAIMS, DAMAGES OR OTHER LIABILITY
ARISING FROM THE MATERIAL OR ITS USE.