# Principles Canonical: https://socra.design/principles The few rules that decide every Socra interface. Real samples, simplicity, value, standardization, intuition, and delight are one decision system, not separate documentation topics. 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 ``` ## Principles ### Instant The user never waits to understand or act when the system could have prepared, because avoidable delay is friction. ### Honest The interface shows true state and never manufactures, hides, or dramatizes it, because a lie costs the user the energy of doubt. ### Quiet Nothing claims attention it has not earned, because chrome that competes with content is friction. ### Effortless The next action is evident and takes one step, and a reversible action completes without asking, because avoidable choice and reading are friction. ### Coherent Every product reads as one system where the same intent looks and behaves the same everywhere, because one system is learned once.