CozyMuseum Design System

The aesthetic foundation of CozyMuseum. This independent repository serves as the single machine-readable source of truth for CozyMuseum's design tokens, CSS runtime, typography, Quiet/Liquid Glass integration contracts, and first-party brand assets.

Designed as a sanctuary for design standards, this system provides resources for the entire CozyMuseum ecosystem without interfering with domain logic, user data, or web infrastructure. All core decisions strictly adhere to ADR-0010 in the platform repository.

Enterprise Architecture

CozyMuseum uses a strict three-tier token dependency graph:

1. Global / Tier 1 (tokens/global/) owns raw values without product context: master colors, type scales, spacing, radius, blur, and duration.
2. Alias / Tier 2 (tokens/alias/) names intent: canvas, foreground, focus, glass surface, control radius, spacing rhythm, typography, and motion.
3. Component / Tier 3 (tokens/component/) binds approved aliases to concrete UI contracts such as Quiet Glass, navigation, buttons, and cards.

Dependencies flow only Global -> Alias -> Component. Global tokens cannot reference another token; Alias tokens cannot reference Component tokens; Component tokens consume Alias tokens instead of raw values. This keeps brand changes centralized while preserving stable consumer interfaces.

Style Dictionary compiles the same source into CSS, SCSS, JavaScript, and JSON. Swift or Android XML output is added only when an approved native consumer exists; unused formats are not generated ceremonially.

Distribution And CI Integrity

• Package identity is @cozymuseum/tokens version 1.0.0, with explicit exports for JavaScript, CSS, SCSS, and JSON.
• Pull requests touching token source or build tooling run npm ci, npm run verify, and a clean generated-build diff gate.
• manifest/published.json remains the authority for byte-addressed CSS, fonts, and first-party brand assets consumed by CozyMuseum.
• The public platform pins an exact design-system commit and manifest checksum; changing this repository requires updating and verifying that consumer in the same release slice.
• Builds may generate build/ and the publication manifest, but must never rewrite the consumer's pin configuration.

Version Authority

Every canonical main commit is exactly one published design-system version. There are no unversioned commits. package.json, the commit message, release notes, generated outputs, manifest, and optional vX.Y.Z tag must identify the same version. Version 1.0.0 is the initial canonical release commit.

Version 1.0.0 Scope

• Master Palette: Deep Green #082118, Red Brown #19140E, Cream White #F2E5D9.
• Typography: Focused on the localized Be Vietnam Pro font family, with a safe fallback to system-ui, sans-serif.
• Three-tier Design Tokens: Global, Alias, and Component contracts using the DTCG-compatible JSON shape.
• Asset Distribution: All currently used CSS, fonts, and brand assets are published byte-for-byte via the styles/, fonts/, and brand/ directories.
• Version Transparency: The manifest/published.json file maintains the provenance, byte size, and SHA-256 hash for every published file.
• UI Standards: Provides Quiet Glass and Liquid Glass examples with graceful fallbacks (e.g., when backdrop-filter is unsupported), alongside configurations for reduced motion and increased contrast.

(Note: Realm accents are not part of the master brand palette. This repository does not contain static UI component frameworks, organism catalogs, or browser runtime data.)

Usage

npm ci
npm run verify

The build output is generated at:

build/css/variables.css
build/scss/_tokens.scss
build/js/tokens.js
build/tokens.json

Client Integration: Consumer CSS can directly import @cozymuseum/tokens/build/css/variables.css. Please refer to examples/quiet-glass.html and examples/quiet-glass.css for the minimal contract.

Change Rules (Invariants)

1. Source of Truth: Only edit source tokens in the correct tokens/global, tokens/alias, or tokens/component tier. Never directly modify compiled files in build/.
2. Brand DNA: The master palette and typography must strictly match the commitments in ADR-0010.
3. Asset Management: Any new asset must be first-party and must appear in the manifest generated by npm run build. Manual modification of the manifest is strictly prohibited.
4. Verification: Run npm run verify, then verify the pinned CozyMuseum consumer before proposing a release.
5. Versioning: Every canonical commit increments Semantic Versioning and represents exactly one published version.
6. Authority: Adding remotes, package registries, tags, or publishing packages requires direct Founder approval.

License

All brand assets, code, and design tokens in this repository are the exclusive proprietary property of CozyMuseum. Nothing in this repository is Open Source. Any unauthorized copying, extraction, or use is strictly prohibited. Please see the LICENSE file for full details.