{ "$schema": "https://simt.space/cosmos-design/specification.schema.json", "version": "2.4.0", "updated": "2026-10-03", "status": "Normative specification", "owner": "SIMT product design and platform maintainers", "base": "https://simt.space/cosmos-design", "scope": "Shared foundations plus four platform parts: web page, web app, mobile app and watch app.", "implementationStatus": "The web product and the mobile product are built on this specification. Conformance is recorded rule by rule in a release record; examples use illustrative data.", "migration": [ "Adds C30: easing is published per platform part in tokens.json under platformAdapters, so a part reads its own curves instead of inferring them.", "C09 and M06 state the Android shape scale (8 / 10 / 14 / 20 / 28 dp) in place of the three-step 12 / 20 / 28, because a handheld screen steps from a 48 dp target to a full-bleed overlay in five increments where a pointer surface needs three, and the Wear round and capsule shapes become normative rather than implied. Both keep their ID and their acceptance criterion.", "The platform mapping is authored in tokens.json as the normative source for every part. A product that diverges from it is out of date with the mapping, and the mapping is never revised to match a product.", "Spacing is unchanged: 1 unit is 1 CSS px on web and 1 dp natively, and no platform publishes its own scale.", "C28 is merged into C09. It repeated the same mapping from a second rule, and one rule that owns the geometry cannot leave a copy of it behind when the mapping changes. No rule ID changed meaning; C28 is free for the next common rule.", "C09, M06 and C17 no longer type a number. The spacing scale, the radius scale and the three durations are read from the token file, so the prose cannot drift from the mapping that an agent reads.", "Every platform part now runs the same three durations. The Android and Wear mapping publishes 150ms feedback, 300ms local state and 500ms context change, and C17 reads that table rather than naming one figure per platform.", "W01 states that corona is the only gradient a watch screen may use, which is what the atmosphere table already implied and what a part payload needs in order to ship one gradient instead of eight.", "Each of the four parts now publishes tokens.json and rules.json at /cosmos-design// carrying the common foundations plus that part's own adapter, so an agent building one platform no longer reads the other three.", "C22 owns those addresses: a payload carries exactly one adapter, publishes the scope it was filtered to, and stays inside a published byte budget. Everything it shares is byte-identical to the canonical document, and filtering may drop a profile but never rewrite one.", "The composited contrast measurements move out of tokens.json into contrast-pairs.json, with the reason to fetch it stated in every file that points at it.", "C05 now names that document as the place the measurements live; C22 owns the rule that a sometimes-needed document gets its own address.", "The token document is 77.5 KiB with the measurements out of it, and one part payload is 78.6 KiB–110.3 KiB against 166.5 KiB for the canonical union. Every measured ratio is unchanged.", "A part payload is now filtered to what that part runs, and the scope it was filtered to is published in the document: the profiles it selects, the gradients its surfaces use, and whether it draws the star layer. The wrist payload, the narrowest of the four, is 24.0 KiB of tokens: a round screen draws one gradient and no stars.", "The gradients a part may use come from the atmosphere table rather than from a second list. Deep Space draws the whole grammar, Daylight keeps horizon and spectrum, astronomy red and watch ambient draw none, and a watch screen narrows further still.", "The oklch projection is published once, as real colour tokens, instead of once per web part as a block of notation strings, and only the parts that can emit an oklch value carry it. It projects the profiles a part actually runs, not all four.", "The token files conform to the design-token standard: a dp radius is a number with its unit in the extension, a native shape is a shape rather than a fake token type, and no group mixes a bare value with its tokens. A tool that reads these files no longer skips a colour.", "Adds C29: colour is authored and verified in sRGB, and every published colour also carries the oklch projection the web parts may author in.", "The Deep Space token registry gains an oklch column. Every hex value is unchanged; the projection is derived, so the two notations cannot disagree.", "Android and Wear declare sRGB in the platform mapping, because neither toolkit has an Oklab colour space to author in.", "Adds C31: a state change is animated by naming the motif whose job is that change. Seven motifs cover the recurring changes — a target acquired, a list revealed, a horizon sweep, the spine advancing, a sheet rising, data going stale, a route change — each publishing its trigger, steps, allowed properties, duration, easing, tier behaviour and CSS, Compose and Wear mapping. A change with no motif does not animate.", "The motifs are published in motion.json, outside the token payloads, with a fetchWhen note saying when to read it. The token files carry the address and a payload never embeds the set, so an agent working on one state change does not read seven choreographies to animate a dim.", "The same document publishes a curve parity fixture: every published easing curve sampled at a fixed number of points by a fixed number of bisection steps, the way the star field publishes its own. A native port reproduces the numbers instead of trusting its toolkit to match, and the fixture carries both the web and the native departure curve because they genuinely differ.", "A section can now carry more than one table, so the motion section publishes the easing mapping and the motif set side by side. The easing purposes are read from the motif module rather than restated, so a table row and a motif cannot name different curves.", "Adds the component index: components.json names, per component, its rule IDs, theme roles, layer and corner role, states, motif and the counterpart each product already has, sliced by platform part. It carries references only — a treatment restated is a second answer that can disagree with the rule it summarises.", "The shared state matrix grows from eight rows to eleven and is now generated. Hover and pressed are separate because a pointer and a finger are different, and confirmed, stale and offline are named because a surface that reaches a data state has to show its confidence. Generated from one vocabulary, so a state with no written treatment fails verification instead of appearing in a table with nothing beside it.", "A component names the motif that animates it and inherits its duration and easing from that motif, so a component repeating the timing was a second copy of motion.json; three actions named a feedback duration beside a motif whose own is state. A component with no motif publishes no timing, which is how a stage that does not animate is stated.", "Every component is now shown at /cosmos-design/gallery, one route per family so each stays inside the per-route HTML budget and a reader can link to one family instead of all of them. A card is a rendering, not a second contract: the state matrix is the rule's own wording, the timing and choreography from the named motif, the colours from the published tokens.", "A gallery card is static HTML. The state matrix is a table, the motif is four still SVG frames, and the Play control ships disabled, so the page explains itself with scripting off and under every theme. Playback is a courtesy on top: one run at a time, nothing on its own, a run that leaves the screen ends rather than resuming unseen, and Static removes the control.", "The duration a card runs is published as a token role rather than a figure, so the client resolves it from the stylesheet and a card cannot state a duration the mapping has moved. Cross-page view transitions between the parts are CSS only and only where the reader has not asked for reduced motion.", "The manifest names the galleries, their families and the components each one shows, derived from the registry. The routes were reachable from the navigation and llms.txt but not from the document an agent loads first.", "Every page carries the site chrome once. A shared page shell let one caller emit its own navigation beside the shell's, putting a second sticky header on six routes; the shell owns the chrome and a check holds each page to one of each.", "A drawing is only as honest as the state it claims to show, and the illustration helpers emitted one style attribute per colour. A browser kept the first and dropped the rest, so 53 gallery and five specimen shapes lost their fill or stroke and a card could not show what it claimed. One helper emits a single merged attribute, and a check refuses a repeated one.", "Every component now accounts for all eleven states, naming the ones it has and the ones it has deliberately opted out of. Of 187 state slots, 102 were unaccounted for, so a component with one state passed. A component opting out gives one of nine codes, each published once as prose, because applicability cannot be derived: the components share sixteen distinct state sets.", "The shared state matrix gains a fourth column naming how many components opt out of each state and by which reason, so coverage is visible on the page.", "A purpose is not a curve: web publishes standard, emphasis, entrance and exit while native adds transform, so a motif naming transform resolved to nothing on a web part and the gate said nothing. Every motif must now resolve on every part it runs on.", "Budget failure messages name the budget and quote its live ceiling, instead of typing a figure that stopped being true when a budget was raised.", "The gallery pages carry the tier picker and the tier is remembered. A reader comparing tiers across seven pages had lost the choice on every navigation, and the picker lived only on the foundations page, so Reduced and Static were unreachable from a gallery. The gallery index carries no picker: it has nothing to play and arrives carrying the stored tier.", "Browser verification covers all thirteen routes and checks the gallery across all three tiers: nothing autoplays, a Static run cannot start even when its button is clicked directly, starting one demo settles the other, and a Reduced run moves no frame and settles into the state a default run does. The tiers are read from the published picker, so a check cannot invent one.", "A run is a crossfade in every tier that has one. It was not: the transition sat on the drawing rather than the frame the script marks, the reduced tier pinned every frame opaque, and both reduced-motion blankets reached the frame with no transition allowed. The fade is not scoped to a tier, because scoping it to Reduced left the reduced run the smoother of the two.", "A card fits a narrow column at large text: the breadcrumb could not wrap and an anatomy identifier has no space to break in, so a 320-pixel page scrolled sideways at doubled text.", "No anchor colour or section URL changed, so every section address stays valid." ], "inheritance": "Platform rules are additive to common; product safety, privacy and accessibility take precedence.", "normativeLanguage": { "must": "Required for conformance.", "should": "Expected unless an explicit evidence-backed exception is recorded.", "may": "Optional within the common constraints." }, "metrics": { "targets": { "web": { "value": 44, "unit": "css-px" }, "android": { "value": 48, "unit": "dp" }, "wear": { "value": 48, "unit": "dp" } }, "webVitals": { "lcpMs": 2500, "inpMs": 200, "cls": 0.1, "percentile": 75 }, "native": { "frameDeadline60HzMs": 16.67, "frameDeadline90HzMs": 11.11, "frameDeadline120HzMs": 8.33, "allowedJankPercent": 5 } }, "budgets": { "htmlBytesPerRoute": 81920, "cssGzipBytes": 20480, "jsGzipBytes": 6144, "initialFontsBytes": 122880, "specificationBytes": 28672, "tokensBytes": 86016, "partTokensBytes": 61440, "partRulesBytes": 61440, "contrastPairBytes": 73728, "motionBytes": 28672, "componentBytes": 24576, "skillBytes": 24576 }, "resources": { "rules": "https://simt.space/cosmos-design/rules.json", "tokens": "https://simt.space/cosmos-design/tokens.json", "skill": "https://simt.space/cosmos-design/cosmos-design-skill.md", "schema": "https://simt.space/cosmos-design/specification.schema.json", "manifest": "https://simt.space/cosmos-design/manifest.json", "markdown": "https://simt.space/cosmos-design/specification.md", "css": "https://simt.space/cosmos-design/tokens.css", "releaseTemplate": "https://simt.space/cosmos-design/release-template.json", "contrastPairs": "https://simt.space/cosmos-design/contrast-pairs.json", "changelog": "https://simt.space/cosmos-design/changelog.md" }, "ruleCount": 80, "pages": [ { "slug": "common", "number": "00", "label": "Common foundations", "title": "One universe.\nA coherent language.", "description": "The shared Cosmos contract: palette, type, geometry, components, accessibility, motion, data and production acceptance.", "url": "https://simt.space/cosmos-design/common", "markdown": "https://simt.space/cosmos-design/common.md", "ruleCount": 30, "sections": [ { "id": "identity", "title": "Identity & authority", "url": "https://simt.space/cosmos-design/common#identity", "ruleIds": ["C01", "C02", "C03"] }, { "id": "palette", "title": "Color with a job", "url": "https://simt.space/cosmos-design/common#palette", "ruleIds": ["C04", "C05", "C06", "C29"] }, { "id": "light", "title": "Light with a job", "url": "https://simt.space/cosmos-design/common#light", "ruleIds": ["C27"] }, { "id": "atmosphere", "title": "Stars at the edge", "url": "https://simt.space/cosmos-design/common#atmosphere", "ruleIds": ["C11"] }, { "id": "typography", "title": "Readable at every scale", "url": "https://simt.space/cosmos-design/common#typography", "ruleIds": ["C07", "C08"] }, { "id": "geometry", "title": "Field, spine, aperture", "url": "https://simt.space/cosmos-design/common#geometry", "ruleIds": ["C09", "C10", "C25", "C26"] }, { "id": "components", "title": "Component contracts", "url": "https://simt.space/cosmos-design/common#components", "ruleIds": ["C12", "C13", "C14", "C15", "C16"] }, { "id": "motion", "title": "Motion earns its place", "url": "https://simt.space/cosmos-design/common#motion", "ruleIds": ["C17", "C18", "C30", "C31"] }, { "id": "accessibility", "title": "Everyone keeps their bearings", "url": "https://simt.space/cosmos-design/common#accessibility", "ruleIds": ["C19", "C20", "C21"] }, { "id": "implementation", "title": "Structured delivery & release", "url": "https://simt.space/cosmos-design/common#implementation", "ruleIds": ["C22", "C23", "C24"] } ] }, { "slug": "web-page", "number": "01", "label": "Web page", "title": "A horizon\nworth exploring.", "description": "Cosmos public and marketing websites: editorial horizons, a useful atlas, product evidence, conversion, SEO and restrained motion.", "url": "https://simt.space/cosmos-design/web-page", "markdown": "https://simt.space/cosmos-design/web-page.md", "ruleCount": 11, "sections": [ { "id": "composition", "title": "The editorial horizon", "url": "https://simt.space/cosmos-design/web-page#composition", "ruleIds": ["P01", "P02"] }, { "id": "layout", "title": "Responsive composition", "url": "https://simt.space/cosmos-design/web-page#layout", "ruleIds": ["P03", "P04"] }, { "id": "atlas", "title": "An atlas that tells the truth", "url": "https://simt.space/cosmos-design/web-page#atlas", "ruleIds": ["P05", "P06"] }, { "id": "conversion", "title": "Confident, calm conversion", "url": "https://simt.space/cosmos-design/web-page#conversion", "ruleIds": ["P07", "P08"] }, { "id": "delivery", "title": "Fast by construction", "url": "https://simt.space/cosmos-design/web-page#delivery", "ruleIds": ["P09", "P10"] }, { "id": "release", "title": "Web page acceptance", "url": "https://simt.space/cosmos-design/web-page#release", "ruleIds": ["P11"] } ], "tokens": "https://simt.space/cosmos-design/web-page/tokens.json", "rules": "https://simt.space/cosmos-design/web-page/rules.json" }, { "slug": "web-app", "number": "02", "label": "Web app", "title": "Every signal.\nIn context.", "description": "Cosmos for Simt Social: continuous map/list discovery, context-preserving detail, activity composition, profiles, inbox and operations.", "url": "https://simt.space/cosmos-design/web-app", "markdown": "https://simt.space/cosmos-design/web-app.md", "ruleCount": 13, "sections": [ { "id": "shell", "title": "A persistent social field", "url": "https://simt.space/cosmos-design/web-app#shell", "ruleIds": ["A01", "A02"] }, { "id": "discovery", "title": "Discover by place, time or people", "url": "https://simt.space/cosmos-design/web-app#discovery", "ruleIds": ["A03", "A04", "A05"] }, { "id": "participation", "title": "Honest participation", "url": "https://simt.space/cosmos-design/web-app#participation", "ruleIds": ["A06", "A07"] }, { "id": "composer", "title": "Compose with continuity", "url": "https://simt.space/cosmos-design/web-app#composer", "ruleIds": ["A08", "A09"] }, { "id": "operations", "title": "A precise operational console", "url": "https://simt.space/cosmos-design/web-app#operations", "ruleIds": ["A10"] }, { "id": "performance", "title": "A responsive working set", "url": "https://simt.space/cosmos-design/web-app#performance", "ruleIds": ["A11", "A12"] }, { "id": "release", "title": "Web app acceptance", "url": "https://simt.space/cosmos-design/web-app#release", "ruleIds": ["A13"] } ], "tokens": "https://simt.space/cosmos-design/web-app/tokens.json", "rules": "https://simt.space/cosmos-design/web-app/rules.json" }, { "slug": "mobile-app", "number": "03", "label": "Mobile app", "title": "A precise instrument.\nWithin reach.", "description": "Cosmos for SIMT Android: compass, map, sky, tracking and tool layouts, adaptive postures, native input, sensors and measured performance.", "url": "https://simt.space/cosmos-design/mobile-app", "markdown": "https://simt.space/cosmos-design/mobile-app.md", "ruleCount": 14, "sections": [ { "id": "anatomy", "title": "The instrument field", "url": "https://simt.space/cosmos-design/mobile-app#anatomy", "ruleIds": ["M01", "M02"] }, { "id": "instruments", "title": "Fixed frame, living reading", "url": "https://simt.space/cosmos-design/mobile-app#instruments", "ruleIds": ["M03", "M04", "M05"] }, { "id": "components", "title": "Native affordances, Cosmos clarity", "url": "https://simt.space/cosmos-design/mobile-app#components", "ruleIds": ["M06", "M07"] }, { "id": "adaptive", "title": "Adapt to the available field", "url": "https://simt.space/cosmos-design/mobile-app#adaptive", "ruleIds": ["M08", "M09"] }, { "id": "sensors", "title": "Accurate data, humane permissions", "url": "https://simt.space/cosmos-design/mobile-app#sensors", "ruleIds": ["M10", "M11"] }, { "id": "performance", "title": "Native performance contracts", "url": "https://simt.space/cosmos-design/mobile-app#performance", "ruleIds": ["M12", "M13"] }, { "id": "release", "title": "Mobile acceptance", "url": "https://simt.space/cosmos-design/mobile-app#release", "ruleIds": ["M14"] } ], "tokens": "https://simt.space/cosmos-design/mobile-app/tokens.json", "rules": "https://simt.space/cosmos-design/mobile-app/rules.json" }, { "slug": "watch-app", "number": "04", "label": "Watch app", "title": "One glance.\nOne useful answer.", "description": "A simplified Cosmos for SIMT Wear OS: round-screen instruments, accessible rotary input, concise tools and battery-aware ambient states.", "url": "https://simt.space/cosmos-design/watch-app", "markdown": "https://simt.space/cosmos-design/watch-app.md", "ruleCount": 12, "sections": [ { "id": "glance", "title": "The single-glance contract", "url": "https://simt.space/cosmos-design/watch-app#glance", "ruleIds": ["W01", "W02"] }, { "id": "type-input", "title": "Readable and reachable", "url": "https://simt.space/cosmos-design/watch-app#type-input", "ruleIds": ["W03", "W04"] }, { "id": "screens", "title": "A small set of useful tools", "url": "https://simt.space/cosmos-design/watch-app#screens", "ruleIds": ["W05", "W06", "W07"] }, { "id": "ambient", "title": "Ambient is a different composition", "url": "https://simt.space/cosmos-design/watch-app#ambient", "ruleIds": ["W08", "W09"] }, { "id": "performance", "title": "Battery is part of UX", "url": "https://simt.space/cosmos-design/watch-app#performance", "ruleIds": ["W10", "W11"] }, { "id": "release", "title": "Watch acceptance", "url": "https://simt.space/cosmos-design/watch-app#release", "ruleIds": ["W12"] } ], "tokens": "https://simt.space/cosmos-design/watch-app/tokens.json", "rules": "https://simt.space/cosmos-design/watch-app/rules.json" } ], "provenance": [ { "repository": "simt-landing (superseded by simt-space)", "paths": ["cosmos-design/index.html", "styles/cosmos-design.less", "scripts/cosmos-design.js"], "observed": "One large guide; page-owned animated star canvases and mixed native/web examples.", "direction": "Replace with a static, linked specification with measurable rules and one optional atmospheric owner." }, { "repository": "simt-social-landing", "paths": ["src/templates/partials/hero.hbs", "src/templates/partials/atlas.hbs", "src/styles/tokens.less"], "observed": "Narrative hero, activity atlas, role discovery, privacy and multilingual public content.", "direction": "Keep the human story and useful atlas; use editorial horizons and actual product evidence." }, { "repository": "simt-social", "paths": ["app/styles/tokens-dark.css", "app/routes/discover.tsx", "mockups/README.md"], "observed": "Canonical warm palette, persistent social shell, map/list discovery, activity composer and moderation console.", "direction": "Preserve route responsibilities; improve context continuity, scanning, recovery and density." }, { "repository": "simt-app", "paths": ["docs/design/COSMOS_REDESIGN.md", "core/ui/src/main/java/app/simt/core/ui/theme/Color.kt", "core/ui/src/main/java/app/simt/core/ui/theme/Motion.kt"], "observed": "Native instrument palette and typography; adaptive maps, dials and tools.", "direction": "Task-first instruments with stable reference frames, deliberate reach zones and system-owned back behavior." }, { "repository": "simt-app/wear", "paths": ["src/main/java/app/simt/wear/screens/HomeScreen.kt", "src/main/java/app/simt/wear/screens/CompassScreen.kt", "src/main/java/app/simt/wear/theme/WearColors.kt"], "observed": "Compass, sky, geofence, plumb bob, targets and settings; cyan has a legacy tool-specific value.", "direction": "One-glance tools with shared signal meaning, round geometry and a genuinely quiet ambient state." } ], "sources": [ { "name": "WCAG 2.2", "url": "https://www.w3.org/TR/WCAG22/", "use": "Web accessibility baseline; Cosmos adopts a stronger 44 CSS px target than the 24 CSS px AA minimum." }, { "name": "Core Web Vitals", "url": "https://web.dev/articles/vitals", "use": "Field LCP, INP and CLS thresholds at the 75th percentile." }, { "name": "Wear accessibility", "url": "https://developer.android.com/design/ui/wear/guides/foundations/accessibility", "use": "Touch geometry, text and assistive input on round screens." }, { "name": "Wear always-on", "url": "https://developer.android.com/training/wearables/always-on", "use": "Ambient lifecycle, burn-in protection and battery-aware behavior." }, { "name": "Design Tokens format", "url": "https://www.designtokens.org/tr/2025.10/format/", "use": "Typed token interchange; exported sRGB components retain exact hex anchors in extensions." } ] }