# Sylhet Design System

> A minimal design system for human and AI builders: readable source, quiet type, 200 layout specifications and optional meaningful sound. By Z7 Studio and Mustafejur Rahman, Founder, Lead Director & Developer.

Default to white/near-black, one restrained green OR orange accent, calm motion and sound off. Respect supplied colors. A sufficient brief should lead directly to implementation; no compulsory questionnaire. Personal/nonprofit use only under LICENSE; selling websites or other business use needs written permission from Z7 Studio. Seek permission/support at https://z7.studio.

Choose green as a starting heuristic for nature/community/care/learning/calm; orange for creative/maker/warm/expressive work. Supplied brand colors take precedence. SDS's own identity uses both; keep a clear primary accent in most consuming pages. Optional place palettes require explicit CSS and are not default themes.

## Start

- [Instructions](AGENTS.md): current agent workflow and source boundaries.
- [Readme](README.md): entry points and quickstart.
- [Getting started](docs/getting-started.md): implementation sequence.
- [AI guide](docs/ai.md): content-first recipe selection and honest outputs.
- [Canonical registry](registry.json): exact modern primitives, exports, defaults, documentation and asset manifest links.
- [Consolidated guides](llms-full.txt): maintained prose guides in one file; catalogue JSON remains separate.

## Foundations and implementation

- [Foundations](docs/foundations.md): visual decisions and restraint.
- [Tokens](docs/tokens.md): canonical --sds-* vocabulary.
- [Type scale](docs/typography-scale.md): text and display classes, Bangla font stack and spacing.
- [Icons](docs/icons.md): sprite, createIcon module and <sds-icon> element.
- [Component library](docs/components/README.md): load sylhet/components/index.css and index.js; overlays, disclosure, feedback, forms, navigation, data display, actions and menus, layout and typography. Live demos in recipes/components/.
- [Place palettes](docs/place-palettes.md): eight optional accent-only combinations, exact IDs, light/dark values and contrast-check scope.
- [Layout](docs/layout.md): composition, order and responsive spans.
- [Typography](docs/typography.md): hierarchy, content and multilingual constraints.
- [Components](docs/components.md): exact primitive markup and behavior boundaries.
- [Accessibility](docs/accessibility.md): semantics, keyboard, alternatives and checks.
- [Images](docs/images.md): crop, alt, performance and provenance.
- [Motion](docs/motion.md): glyph display, still/reduced motion and Lottie boundaries.
- [Sound](docs/sound.md): exact opt-in audio API and graceful failure.
- [Code](docs/code.md): integration, source structure and application responsibilities.

## Layout selection

- [Layout data](data/layouts.json): 200 specification objects across 20 families, 70 section types.
- [JSON Schema](data/layouts.schema.json): version 1.0.0 data shape.
- [Schema guide](docs/layout-schema.md): fields, spans, budgets and selection.
- [Human catalogue](docs/layout-catalog.md): every recipe and its reading sequence.
- [Runnable preview index](previews/index.html): 200 responsive composition scaffolds with explicit sample content; not finished or individually audited websites.
- [Generator](scripts/build-layout-catalog.mjs): authored source and structural validation.
- [Preview generator](scripts/build-layout-previews.mjs): renders semantic section anatomy and responsive spans from layout data.

## Verification and rights

- [Quality gates](docs/quality.md): concrete browser, keyboard, audio and failure checks.
- [Evidence](docs/evidence.md): official Primer/shadcn/Material/Carbon references; sound prior art.
- [License guide](docs/license.md): permission and attribution explanation.
- [License](LICENSE): controlling personal/nonprofit terms.

## Source boundaries

Modern runtime: sylhet/sds.css and sylhet/sds.js, with .sds-*, --sds-* and data-sds-* APIs. Supported accent values are orange and green; motion values calm and still; dark scheme is explicit. Read source for exact behavior. A CSS primitive is not a complete interactive widget.

Legacy runtime: sylhet/sylhet.css, sylhet/sylhet.js and data/legacy-registry.json use separate sy-* APIs. Original recipes and docs HTML remain historical reference; docs/legacy instructions do not override current AGENTS.md. Do not load both complete bases accidentally. Root registry.json is the modern discovery contract.

Layout entries are specifications, not finished or individually browser-tested sites. Lottie slots are suggestions, not asset IDs. Do not invent sample provenance, email addresses, statistics or endorsements. SDS is not the first system to document sound: Material 2 has explicit sound guidance.

## Recreate the showcase

- [Expressive motion contract](docs/expressive-motion.md): the actual counted opening, orange column wipe, colorful grid, square orbit, Lottie studies, floating words, square actions and ending used by the main site.
- [Reproduction prompt](prompts/recreate-expressive-site.md): complete implementation brief for people and AI.
- [Native motion atlas](recipes/motion-atlas.html): small scenes without the whole-page runtime.
- [Expressive page recipe](recipes/expressive/index.html): exact required structure, public module and self-hosted runtime.

## Compose and study whole websites

- [Website studies](docs/website-layouts.md): twelve distinct websites, three linked pages each; human study and editable source.
- [Website plan data](data/website-layouts.json): exact page/part/variant sequences for all twelve studies.
- [Layout desk](docs/designer.md): local drag/drop editor, responsive preview, JSON, AI brief and HTML export.
- [Saved-layout schema](data/designer.schema.json): version 1 normalized design files, at most six pages and 32 parts/page.
- [MCP plan](docs/mcp-plan.md): implemented optional read-only tools/resources; remote release disabled by default.
- [Free MCP hosting](docs/deploy-mcp-free.md): stateless Cloudflare Free within quotas, or local stdio; model use and generation are separate.

- [Website deployment](docs/deploy-website.md): complete static output, origin metadata and deployment verification.

- [Independent deployments](docs/deploy.md): separate website and MCP packages, full GitHub/Vercel/Cloudflare guides, no website runtime coupling.
