# Colors & Effects Canonical: https://socra.design/theme/colors-effects Touch the palette, depth, and glass. The theme is a surface you play with. Implement Colors & Effects through the owning platform package so products share its intent and behavior while preserving native interaction. Status: ready. @socra/theme exposes palette, background, text, and semantic color roles plus shadow elevation and motion primitives. Library: @socra/theme ## Anatomy - Intent, states, feedback, hierarchy, and access requirements are independent of any renderer. - Every shared visual relationship resolves from semantic design roles without changing their meaning between platforms. - Each platform uses its native mechanics and provides live conformance evidence without changing the guideline. ## 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`: The primary brand action and emphasis for the active color mode. - `designTokens.color[mode].color.brand.hover`: The hover emphasis for a primary brand interaction. - `designTokens.color[mode].color.brand.active`: The pressed or active emphasis for a primary brand interaction. - `designTokens.color[mode].color.brand.onPrimary`: Content that appears on the primary brand surface. - `designTokens.color[mode].color.brand.accent`: Supporting brand emphasis that does not compete with the primary action. - `designTokens.color[mode].color.feedback.info.foreground`: Readable content for info feedback. - `designTokens.color[mode].color.feedback.info.background`: Containing surface for info feedback. - `designTokens.color[mode].color.feedback.info.border`: Boundary for info feedback. - `designTokens.color[mode].color.feedback.success.foreground`: Readable content for success feedback. - `designTokens.color[mode].color.feedback.success.background`: Containing surface for success feedback. - `designTokens.color[mode].color.feedback.success.border`: Boundary for success feedback. - `designTokens.color[mode].color.feedback.warning.foreground`: Readable content for warning feedback. - `designTokens.color[mode].color.feedback.warning.background`: Containing surface for warning feedback. - `designTokens.color[mode].color.feedback.warning.border`: Boundary for warning feedback. - `designTokens.color[mode].color.feedback.danger.foreground`: Readable content for danger feedback. - `designTokens.color[mode].color.feedback.danger.background`: Containing surface for danger feedback. - `designTokens.color[mode].color.feedback.danger.border`: Boundary for danger feedback. - `designTokens.color[mode].color.border.subtle`: subtle structural separation by semantic strength. - `designTokens.color[mode].color.border.standard`: standard structural separation by semantic strength. - `designTokens.color[mode].color.border.strong`: strong structural separation by semantic strength. - `designTokens.color[mode].color.border.focus`: focus structural separation by semantic strength. - `designTokens.accessibility.contrast.text`: Minimum contrast relationship for text. - `designTokens.accessibility.contrast.largeText`: Minimum contrast relationship for largeText. - `designTokens.accessibility.contrast.nonText`: Minimum contrast relationship for nonText. - `designTokens.color[mode].color.surface.background`: The application background beneath everything else. - `designTokens.color[mode].color.surface.secondary`: The ordinary content surface, nested on the background. - `designTokens.color[mode].color.surface.tertiary`: The deepest nested surface; surfaces never nest further. - `designTokens.color[mode].color.content.primary`: Essential labels, content, and decisions. - `designTokens.color[mode].color.content.secondary`: Explanatory copy and supporting metadata. - `designTokens.color[mode].color.content.muted`: Quiet enabled copy with reduced emphasis. - `designTokens.color[mode].color.content.disabled`: Content for unavailable controls only. - `designTokens.color[mode].color.content.inverse`: Content on an inverse surface. - `designTokens.color[mode].color.content.link`: Navigational content. - `designTokens.elevation.role.resting`: Content at rest on its owning surface. - `designTokens.elevation.role.card`: Grouped content raised from a surface. - `designTokens.elevation.role.menu`: Transient action or selection content. - `designTokens.elevation.role.dialog`: Focused, blocking task content. - `designTokens.elevation.role.showcase`: Prominent presentation content. - `designTokens.elevation.order`: The four-layer ordering — content, sticky, overlay, glass — where a layer decides shadow, glass treatment, and stacking together. - `designTokens.motion.intent.acknowledge`: Immediate feedback that an action was received. - `designTokens.motion.intent.transition`: Movement between stable interface states. - `designTokens.motion.intent.reveal`: The appearance of newly available content. - `designTokens.motion.intent.dismiss`: The removal of transient content. - `designTokens.state.opacity.disabled`: The shared disabled opacity relationship. - `designTokens.state.opacity.muted`: The shared muted opacity relationship. - `designTokens.state.opacity.hoverWash`: The shared hoverWash opacity relationship. - `designTokens.state.opacity.selectedWash`: The shared selectedWash opacity relationship. - `designTokens.state.opacity.focusWash`: The shared focusWash opacity relationship. - `designTokens.state.emphasis.rest`: The shared rest emphasis relationship. - `designTokens.state.emphasis.hover`: The shared hover emphasis relationship. - `designTokens.state.emphasis.active`: The shared active emphasis relationship. ## Example ```tsx ```