# Design Language Canonical: https://socra.design/principles/design-language The normative shape, color, glass, elevation, typography, spacing, and content rules. Use the shared visual grammar as one connected system: semantic roles communicate hierarchy and action, while arbitrary renderer values and component-local styling create drift. Status: ready. Prefilled as the decision system for every future page. Library: UI knowledge ## Anatomy - A named user outcome. - A decision rule that removes subjective taste. - A semantic design relationship and platform conformance reference whenever the rule reaches UI. - A deletion test: if the element does not create value, simplify or remove it. ## States - **Rest:** Shows the stable, enabled component without implied activity. - **Hover:** Adds pointer affordance without moving content or changing meaning. - **Focus:** Shows the shared visible focus treatment without depending on hover. - **Pressed:** Acknowledges active input immediately and returns cleanly on release. - **Selected:** Uses a neutral surface plus native selected semantics when selection applies. - **Disabled:** Remains legible, unavailable, and absent from misleading interaction feedback. - **Loading:** Preserves context while honestly identifying work that has not completed. - **Error:** Places the failure and recovery path beside the action or content that failed. ## Motion Stable state changes respond immediately. Appearance, expansion, and morphing begin at the triggering origin and use an interruptible spring that can retarget from its live position and velocity. When spatial motion is not meaningful, the component changes without decorative travel. ## Usage - Use the owning platform implementation first. Each renderer improves once and every product on that platform inherits the fix. - Name the user job before the component. A component earns a place only when it helps the user decide, act, recover, or understand. - Promote missing behavior into the owning platform domain. Product-local UI creates drift; platform contracts preserve shared meaning and native quality. - Raise luminance to bring a surface forward. Depth reads as light. A surface that comes toward the reader catches more of it, so a raised panel, a selected tab, a menu, a popover resolves LIGHTER than what it sits on — in dark mode away from the canvas, in light mode toward the white it cannot exceed. The ladder runs page, resting card, elevated, and never doubles back. ## Avoid - Do not build a product-local replacement. A local implementation splits behavior, access requirements, and future migrations. - Do not copy theme values. Semantic values are shared system roles and are consumed by meaning. - Do not add decoration as a substitute for structure. If the hierarchy is weak, fix the hierarchy. - Do not darken a surface to lift it. Darkening in a dark theme pushes a surface INTO the page — it reads as a hole cut in the canvas rather than a panel resting on it. Sinking a surface to make it stand out is the most common way a dark interface loses its depth. ## Tokens - `designTokens.color[mode].color.brand.primary`: One primary action per screen. - `designTokens.spacing.role.contentGap`: Use semantic relationships instead of local measurements. - `designTokens.accessibility.target.minimum`: Equivalent access begins with a viable interaction target. ## Example ```tsx ``` ## Guidelines ### Shape Every squircle uses token-derived continuous-curvature corners. Controls and compact containers use 20px across products and viewports; large showcase and routing cards use 32px; the primary composer input in Cortex and Journeys uses 40px; true circles and semantic pills retain their round geometry (design). ### Nested radii Nested radii are derived as outer radius minus padding. ### Surfaces Exactly three surface roles exist: background, secondary, and tertiary, the fewest that show containment depth without borders (design). ### Nesting Surfaces nest at most three deep and read darkest-to-lightest from outside-in in both modes, so depth reads in one direction everywhere (design). ### Component colors Component-named surface colors do not exist. ### Text hierarchy Secondary text uses neutral foreground hues—60, 60, 67 in light contexts and 235, 235, 245 in dark contexts—with sufficient opacity to maintain at least 5:1 contrast against every supported surface (design). ### Accent Socra cyan is the theme’s one accent hue and only brand color inside products, using #0090B0 in light mode and #29C4E8 in dark mode (design). ### Selection Selection uses a neutral surface plus native semantics, never a primary or brand highlight, because selection is the user's state and never a promotion (design). ### Calls to action One filled action on a screen identifies what to do next (design). ### Applied switch state A checked switch may fill its track with the accent because the fill makes its current state obvious (design). ### Revealed actions A state that reveals actions floats them clear of the content and changes no element's box, because the reader is looking at what they just acted on and text that moves under a finger has to be found again. ### Reveal placement A revealed surface that cannot fit beside the element it acts on resolves to its other side rather than over it. ### Glass Glass is reserved for floating functional layers, never content chrome; glass never stacks and derives its tint from underlying content, because glass marks a floating functional layer and chrome that blurs content hides it (design). ### Elevation Elevation orders content below sticky below overlay below glass; the layer determines shadow, glass treatment, and stacking together. ### Type family Web surfaces on macOS, iOS, and iPadOS use the system interface font; all other platforms use Inter, one quiet family so hierarchy comes from published scale and weight, never from novelty (design). ### Type roles Text uses published typography types; manual font sizes and weights are forbidden, because one manual size forks the hierarchy the system promises. ### Spacing Spacing is 8 within groups, 16 between groups, and 32 between sections, so grouping is shown by space before any divider needs to exist (design). ### Content A control names the outcome of its action, such as “Save changes”; vague labels such as “OK” and “Submit” are not allowed.