{"version":"1.1.0","name":"StillWell","url":"https://stillwellapp.com/design","description":"A calm, clear identity for sound therapy and daily wellbeing. Shared guidance for the website, mobile app and marketing.","scope":"Documents existing visual foundations and establishes contribution rules. Component previews are reference specimens, not a claim that every existing screen already meets every rule. Older marketing briefs may contain outdated colours, product facts or claims; use current source code and verified product information.","principles":[{"title":"Make room for calm","body":"Use deep or softly tinted backgrounds, generous space and restrained accents. Each screen or creative should have one clear focus."},{"title":"Be human and clear","body":"Speak to a person, not a diagnosis. Use everyday language, short sentences and a useful next step."},{"title":"Earn trust","body":"Show the real product. Be specific about what a feature does and honest about the limits of any claim."},{"title":"Keep the family resemblance","body":"Carry the same colour relationships, soft shapes and measured tone across platforms. Keep native controls native."}],"identity":["Write StillWell with a capital S and W. Use The StillWell Program for the named program; use sentence case elsewhere.","Use the supplied assets. The website favicon, Apple touch icon and native app icon are distinct existing assets; do not silently substitute one for another or redraw their waveforms.","For new layouts, leave clear space of at least one quarter of the icon width on each side. Show the website mark at 24 px or larger; use the native icon at appropriate platform resolution.","Keep marks proportional, upright and unaltered. Do not recolour, stretch, add shadows to, or place busy imagery behind the mark. The wordmark uses a clean semibold sans-serif alongside the supplied mark."],"typography":[{"role":"Display","web":"48–64 px / 1.1–1.2 · 700","mobile":"30–36 pt · 700","use":"Short hero headlines. One dominant message."},{"role":"Heading","web":"24–32 px / 1.25 · 600","mobile":"24–30 pt · 600–700","use":"Section and screen titles."},{"role":"Title","web":"18–20 px / 1.4 · 600","mobile":"18–20 pt · 600","use":"Cards, sheet titles and important labels."},{"role":"Body","web":"16–18 px / 1.6–1.8 · 400","mobile":"16 pt · 400","use":"Readable, short paragraphs. Aim for 45–75 characters per line on the web."},{"role":"Caption","web":"12–14 px / 1.5 · 400–500","mobile":"12–14 pt · 400–500","use":"Supporting metadata, never the only place for essential instructions."}],"typographyRules":["Website: use the bundled Mona Sans variable font (200–900). The font-display utility sets the width axis to 125 for editorial headings. Do not stretch ordinary body text.","Mobile: use React Native system typography, including San Francisco on iOS. No custom UI font is loaded by the app. Allow font scaling and flexible text height.","Marketing: use Mona Sans for designed artwork; use the platform system sans-serif if Mona Sans is unavailable. Use one type family per creative.","The scale above is contribution guidance based on existing usage. Tailwind v4 text-* utilities use its --text-* scale; the legacy --font-size-* variables in globals.css are used explicitly by rich-text styles and do not redefine those utilities."],"layout":{"spacing":[4,8,12,16,24,32,48,64,96],"radii":[{"name":"Small","value":8,"use":"Icon tiles and compact controls"},{"name":"Medium","value":12,"use":"List items and inputs"},{"name":"Large","value":16,"use":"Standard cards"},{"name":"Feature","value":24,"use":"Large grouped surfaces"}],"rules":["Use a 4-unit spacing base. Web units are CSS pixels; native dimensions are logical points. Prefer Tailwind spacing utilities over arbitrary values.","Website content uses a centred max-w-7xl container (1280 px), 24 px side padding and 64–96 px section spacing. Collapse grids as space decreases.","Mobile cards typically use 16 px padding and a 16 px radius. Respect safe areas, keyboard insets and large text settings.","Use a fully rounded shape for badges and play controls. Hairline white borders at 5–10% opacity separate dark web surfaces; essential control boundaries need stronger contrast.","Web cards commonly use white at 2–5% over the canvas, with a subtle emerald hover border. Native cards use bg-surface, not copied web hex colours. Native dark shadows are transparent; light-mode shadows come from the theme."]},"colours":["The /design reference supports Light, Dark and System themes. System follows the device preference; an explicit choice is remembered in this browser. The light canvas is #f6f8f5 with #172e22 text and #08734e accents. Other marketing routes currently retain their dark presentation.","Use the designThemes light/dark semantic pairs in /design/tokens.json for the guide’s interface. Controls, surfaces and text change together. The native preview has its own theme selector; fixed colour swatches and labelled dark artwork specimens keep their original colours.","Website foundations: bg-canvas (#0a0f0d), bg-panel (#0d1210), white primary text and neutral-300/400 supporting text. Use emerald-400 for links and emphasis on dark surfaces.","Asset colours: #10b981 and #2dd4bf come from the existing favicon. Tailwind v4 emerald/teal utilities use OKLCH values and are not exact aliases for these legacy hex values.","The website highlight gradient runs emerald-400 → teal-300 → cyan-400. Keep gradients to short display text, icon tiles or soft ambient glows. Set body text in a solid colour.","Mobile defaults to the mint palette and follows the system light/dark preference. Use semantic roles: background, foreground, surface, surface-foreground, accent, accent-foreground, muted, divider, success, warning and danger.","Mint and alpha light/dark variants are defined and registered in Metro. Default light/dark come from HeroUI. Lavender and sky names appear in the context type but are not currently registered palettes; do not treat them as supported themes.","Preserve exact native OKLCH source values. Some colours require gamut mapping on sRGB output. Check actual rendered contrast, particularly muted text and light-mode accents; a token is not an accessibility guarantee."],"components":[{"name":"Primary action","source":"stillwell-web/src/components/marketing/components.tsx · AppStoreButton","rule":"One primary action per section. The current marketing download action is white with dark text. Use a descriptive verb; show visible hover, focus, pressed, disabled and loading states."},{"name":"Feature card","source":"stillwell-web/src/components/ui.tsx · FeatureCard","rule":"16 px radius, 24 px padding, quiet border, accent icon tile, concise heading and supporting text. Keep the whole card static unless it has a meaningful destination."},{"name":"Sound card","source":"mobile-app/src/components/sounds/SoundCard.tsx","rule":"Semantic surface, 16 px radius and padding, 48 px leading control. Show sound name, description and separate favourite action. Make playing and locked states understandable without colour."},{"name":"Player & timer","source":"mobile-app/src/components/sounds/MiniPlayer.tsx · SleepTimerSheet.tsx","rule":"Separate playback, volume and timer actions. Label icon buttons. Show current playback state in text. Never start audio without the listener choosing to play."},{"name":"Forms & sheets","source":"mobile-app/src/components/profile/ · heroui-native","rule":"Use labelled fields, inline errors and native sheet primitives. Keep entered values on recoverable errors. Restore focus after a dialog closes and keep dismiss actions reachable."},{"name":"Progress & feedback","source":"mobile-app/src/components/sessions/GoalProgress.tsx · StreakBadge.tsx","rule":"Pair rings with a number and text. Celebrate gently without pressure or implying a health outcome. Use explicit success, warning and error labels alongside semantic colours."}],"motion":["Use a calm pace: 150–300 ms for interaction feedback. Existing web entrance animations use a 600 ms ease-out fade with up to 30 px upward travel; stagger steps by 100 ms when appropriate.","Respect prefers-reduced-motion on the web and the native reduced-motion preference. Remove decorative movement and repeating waves; all content must remain visible without animation or JavaScript.","Waveforms communicate sound, not measured clinical change. Never flash, pulse urgently, simulate tinnitus with piercing tones, or autoplay audio in marketing."],"accessibility":["Target WCAG 2.2 AA: at least 4.5:1 for ordinary text, 3:1 for large text and meaningful interface graphics. Test actual foreground/background pairs in every theme and state.","Use at least 44 × 44 CSS px or native points for touch controls. Keep visible keyboard focus, logical heading order and a skip link. Icon-only actions need accessible names.","Never use colour or sound alone to communicate state. Add text labels, captions for spoken content and useful alt text for meaningful imagery. Hide purely decorative artwork from assistive technology.","Check a 320 px viewport, 200% zoom, long labels, native font scaling, keyboard operation and reduced motion. Essential content must reflow without being clipped."],"voice":[{"quality":"Warm","say":"Find a sound that feels right for you.","avoid":"Your tinnitus is ruining your life."},{"quality":"Clear","say":"Choose a sound. Set a timer. Take a moment.","avoid":"Optimise your neuroacoustic wellness journey."},{"quality":"Measured","say":"Make space for a calmer daily routine.","avoid":"Cure tinnitus in 12 weeks. Guaranteed."},{"quality":"Encouraging","say":"Start again whenever you’re ready.","avoid":"You lost your streak. Don’t fall behind."}],"writing":["Use British English (personalised, colour, favourite) for brand copy, except official feature names and platform labels. Use sentence case, everyday words and direct, gentle calls to action.","Describe features and possibilities without promising a cure, guaranteed relief, a fixed recovery time or universal results. Do not turn general research findings into StillWell user success rates.","Verify statistics, research quotations, testimonials, ratings, prices, sound counts and availability before publishing. Do not invent endorsements or recycle unverified claims from old marketing files.","Keep evidence and its context together. Cite the underlying source for any medical or numerical claim and have health-related copy reviewed. This design system supplies brand rules, not clinical advice."],"imagery":["Use real, current app captures for product imagery. Prefer dark mint for campaign artwork while still showing light mode when relevant. Label illustrative UI and sample data so they cannot be mistaken for the shipped app or a real outcome.","Choose spacious nature photography, soft light, still water or restrained abstract sound forms. Preserve a quiet area for text. Avoid distressed faces, clinical imagery used as an endorsement, busy collages and neon effects.","Web icons use simple SVG line work with rounded caps, typically 20–24 px and 1.5–2 px strokes. Mobile uses Ionicons. Existing category emoji may stay in product context; do not mix multiple decorative icon styles in one creative.","Use licensed or owned media. Add final copy and the supplied mark as separate layout layers after generating imagery; do not ask an image model to invent the logo or reproduce the app UI."],"social":{"note":"These are StillWell working templates, not a statement of current platform upload requirements. Check the destination preview and cropping before publishing.","formats":[{"name":"Portrait post","width":1080,"height":1350,"ratio":"4:5","inset":"80 px","use":"One idea, short headline, small brand signature."},{"name":"Square post","width":1080,"height":1080,"ratio":"1:1","inset":"80 px","use":"Simple educational cards and reusable carousel slides."},{"name":"Vertical story","width":1080,"height":1920,"ratio":"9:16","inset":"90 px sides; 250 px top/bottom","use":"Keep essential text away from interface overlays; check platform preview."}],"recipe":["Start with the deep green canvas. Add one subtle emerald/teal glow or a calm licensed image. Keep a large area of negative space.","Set a short headline in Mona Sans semibold/bold (64–88 px on a 1080 px canvas); supporting copy at 32–40 px. Use white text and at most one short accent phrase.","Keep the supplied logo and StillWell name together with clear space. Place the signature consistently. Use one gentle CTA and avoid crowding the footer.","For carousels, put one idea on each slide and retain the same margins and title position. Put citations on the relevant slide or in its accompanying caption, not in unreadable fine print.","Export raster artwork in sRGB. Review at phone size, add alt text and captions, verify factual claims and check the actual platform crop. Sample layouts here are illustrative, not testimonials or product screenshots."]},"assets":[{"name":"Website mark","path":"/favicon.svg","format":"SVG · existing favicon","source":"stillwell-web/public/favicon.svg"},{"name":"Apple touch icon","path":"/apple-icon.svg","format":"SVG · existing web touch icon","source":"stillwell-web/public/apple-icon.svg"},{"name":"Native app icon","path":"/design/assets/app-icon.png","format":"PNG · native source asset","source":"mobile-app/assets/icon.png"},{"name":"App Store badge","path":"/download-app-store.svg","format":"SVG · existing download badge","source":"stillwell-web/public/download-app-store.svg"}],"workflow":["Read /design/brand.md before starting. Fetch /design/tokens.json for exact colour values and /design/system.json for all structured guidance. Choose the website, native or marketing rules for the target surface.","Reuse existing components and supplied assets. Native additions use HeroUI Native and Uniwind semantic tokens; website additions use the shared canvas tokens, Tailwind and the existing marketing components.","Keep copy concise and verify every product or health claim against a current source. State any unresolved fact instead of inventing it.","Review responsive layouts, light/dark native themes, keyboard and screen-reader labels, contrast, loading/error/disabled states, reduced motion and image rights before handing off.","When changing foundations, update their source CSS and run npm run design:sync in stillwell-web. Run npm run design:check to detect drift. Update design-system.ts and its version when changing guidance; the page, Markdown and JSON all read that same record."],"agentBrief":"Create for StillWell using https://stillwellapp.com/design/brand.md and https://stillwellapp.com/design/tokens.json. Use the appropriate light or dark semantic palette, restrained emerald/teal accents, generous space, rounded surfaces and clear sans-serif typography. The design reference supports light, dark and system preferences; existing marketing routes use dark green. Website: Mona Sans. Mobile: native type, mint semantic tokens and light/dark support. Use the supplied brand assets without redrawing them. Write warm, concise British English. Never invent product facts, testimonials, clinical claims or guaranteed outcomes. Follow the target surface’s rules, verify accessibility and actual platform crops, and report any unresolved facts. Fetch /design/system.json for the full structured guide.","tokens":{"schemaVersion":1,"description":"Generated from source CSS. Values are CSS strings, not approximate hex. Mobile aliases require HeroUI Native/Uniwind. Do not edit by hand.","web":{"source":"stillwell-web/src/app/brand-tokens.css","tokens":{"color-canvas":"#0a0f0d","color-panel":"#0d1210","color-brand-emerald":"#10b981","color-brand-teal":"#2dd4bf"},"designThemes":{"source":"stillwell-web/src/app/design/design.module.css","light":{"canvas":"#f6f8f5","foreground":"#172e22","muted":"#52675a","secondary":"#354d3e","heading-muted":"#567360","line":"#193b2426","accent":"#08734e","surface":"#eaf0e9","surface-hover":"#dfeae1","control-border":"#708978","control-background":"#173e29","control-foreground":"#ffffff","control-hover":"#21553a","selected-background":"#d4eedd","selected-foreground":"#174d31","accent-border":"#79a48a","accent-muted":"#08734e","warning-text":"#944225"},"dark":{"canvas":"#0a0f0d","foreground":"#f4f7f5","muted":"#a3aaa6","secondary":"#b4bfb7","heading-muted":"#95a99e","line":"#ffffff1a","accent":"var(--color-emerald-400)","surface":"#ffffff05","surface-hover":"#ffffff0d","control-border":"#6b8977","control-background":"#f3f7f4","control-foreground":"#0a0f0d","control-hover":"#d9f5e5","selected-background":"#164831","selected-foreground":"#baf4d1","accent-border":"#3c5e4b","accent-muted":"#68b592","warning-text":"#e3b9a6"}},"tailwind":{"color-white":"#fff","color-black":"#000","color-neutral-300":"oklch(87% 0 0)","color-neutral-400":"oklch(70.8% 0 0)","color-neutral-500":"oklch(55.6% 0 0)","color-neutral-800":"oklch(26.9% 0 0)","color-neutral-900":"oklch(20.5% 0 0)","color-neutral-950":"oklch(14.5% 0 0)","color-emerald-300":"oklch(84.5% 0.143 164.978)","color-emerald-400":"oklch(76.5% 0.177 163.223)","color-emerald-500":"oklch(69.6% 0.17 162.48)","color-emerald-600":"oklch(59.6% 0.145 163.225)","color-emerald-950":"oklch(26.2% 0.051 172.552)","color-teal-300":"oklch(85.5% 0.138 181.071)","color-teal-400":"oklch(77.7% 0.152 181.912)","color-teal-500":"oklch(70.4% 0.14 182.503)","color-teal-600":"oklch(60% 0.118 184.704)","color-teal-950":"oklch(27.7% 0.046 192.524)","color-cyan-400":"oklch(78.9% 0.154 211.53)"}},"mobile":{"mint-light":{"source":"mobile-app/src/themes/mint.css","tokens":{"background":"var(--white)","foreground":"oklch(0.22 0.05 170)","surface":"oklch(0.98 0.01 170)","surface-foreground":"oklch(0.28 0.055 170)","overlay":"oklch(0.998 0.003 170)","overlay-foreground":"oklch(0.28 0.055 170)","muted":"oklch(0.52 0.04 170)","default":"oklch(0.94 0.02 170)","default-foreground":"oklch(0.38 0.06 170)","accent":"oklch(0.7 0.16 175)","accent-foreground":"oklch(0.98 0.005 175)","field-background":"oklch(0.98 0.01 170)","field-foreground":"oklch(0.22 0.05 170)","field-placeholder":"var(--muted)","field-border":"transparent","success":"oklch(0.75 0.15 155)","success-foreground":"oklch(0.22 0.08 155)","warning":"oklch(0.8 0.13 95)","warning-foreground":"oklch(0.28 0.08 95)","danger":"oklch(0.66 0.19 25)","danger-foreground":"oklch(0.98 0.005 25)","segment":"oklch(0.98 0.01 170)","segment-foreground":"oklch(0.22 0.05 170)","border":"oklch(0 0 0 / 0%)","divider":"oklch(0.92 0.016 170)","link":"oklch(0.62 0.15 175)","surface-shadow":"0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06)","overlay-shadow":"0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09)","field-shadow":"0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06)"}},"mint-dark":{"source":"mobile-app/src/themes/mint.css","tokens":{"background":"oklch(0.078 0 0)","foreground":"oklch(0.95 0.01 170)","surface":"oklch(0.19 0.05 170)","surface-foreground":"oklch(0.91 0.015 170)","overlay":"oklch(0.22 0.048 170)","overlay-foreground":"oklch(0.91 0.015 170)","muted":"oklch(0.48 0.045 170)","default":"oklch(0.24 0.052 170)","default-foreground":"oklch(0.89 0.018 170)","accent":"oklch(0.68 0.18 175)","accent-foreground":"oklch(0.12 0.045 175)","field-background":"var(--default)","field-foreground":"var(--foreground)","field-placeholder":"var(--muted)","field-border":"transparent","success":"oklch(0.7 0.17 158)","success-foreground":"oklch(0.96 0.008 158)","warning":"oklch(0.76 0.15 98)","warning-foreground":"oklch(0.18 0.04 98)","danger":"oklch(0.64 0.2 28)","danger-foreground":"oklch(0.96 0.008 28)","segment":"oklch(0.21 0.049 170)","segment-foreground":"oklch(0.91 0.015 170)","border":"oklch(0 0 0 / 0%)","divider":"oklch(0.26 0.048 170)","link":"oklch(0.72 0.16 175)","surface-shadow":"0 0 0 0 transparent inset","overlay-shadow":"0 0 0 0 transparent inset","field-shadow":"0 0 0 0 transparent inset"}},"alpha-light":{"source":"mobile-app/src/themes/alpha.css","tokens":{"background":"var(--white)","foreground":"var(--eclipse)","surface":"var(--white)","surface-foreground":"var(--foreground)","overlay":"var(--white)","overlay-foreground":"var(--foreground)","muted":"var(--color-neutral-500)","default":"var(--color-neutral-50)","default-foreground":"var(--eclipse)","accent":"var(--color-neutral-950)","accent-foreground":"var(--snow)","field-background":"var(--default)","field-foreground":"var(--foreground)","field-placeholder":"var(--muted)","field-border":"transparent","success":"oklch(0.5503 0.1244 153.56)","success-foreground":"var(--snow)","warning":"oklch(0.7186 0.1521 64.85)","warning-foreground":"var(--eclipse)","danger":"oklch(0.6259 0.1908 29.19)","danger-foreground":"var(--snow)","segment":"var(--white)","segment-foreground":"var(--eclipse)","border":"var(--color-neutral-200)","divider":"var(--color-neutral-400)","link":"var(--foreground)","surface-shadow":"0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06)","overlay-shadow":"0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09)","field-shadow":"0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06)"}},"alpha-dark":{"source":"mobile-app/src/themes/alpha.css","tokens":{"background":"var(--black)","foreground":"var(--snow)","surface":"var(--eclipse)","surface-foreground":"var(--foreground)","overlay":"var(--color-neutral-800)","overlay-foreground":"var(--foreground)","muted":"var(--color-neutral-400)","default":"var(--color-neutral-900)","default-foreground":"var(--snow)","accent":"var(--color-neutral-50)","accent-foreground":"var(--eclipse)","field-background":"var(--default)","field-foreground":"var(--foreground)","field-placeholder":"var(--muted)","field-border":"transparent","success":"oklch(0.5503 0.1244 153.56)","success-foreground":"var(--snow)","warning":"oklch(85% 0.1414 77.88)","warning-foreground":"var(--eclipse)","danger":"oklch(0.5798 0.1635 30.83)","danger-foreground":"var(--snow)","segment":"var(--color-neutral-900)","segment-foreground":"var(--foreground)","border":"var(--color-neutral-800)","divider":"var(--color-neutral-600)","link":"var(--foreground)","surface-shadow":"0 0 0 0 transparent inset","overlay-shadow":"0 0 0 0 transparent inset","field-shadow":"0 0 0 0 transparent inset"}}}}}