Socra Human Interface Guidelines
Guidance, live primitives, token semantics, and conformance rules for building every Socra product from one system.
Design Fundamentals
The system starts with laws, not taste. Product UI compounds only when every screen inherits the same values, primitives, states, and gates.
System laws
Every UI value comes from the theme, every primitive comes from the UI stack, and missing pieces are promoted into the library.
Token semantics
Tokens are named by role, not taste. The docs explain when to use a token without copying the value.
Token semantics
Component contracts
Each component has state, accessibility, mobile, and dark-mode behavior before product teams compose it.
Foundations Of Design
Foundations define the grammar every product uses: accessibility, color, layout, motion, type, surfaces, writing, and iconography.
New And Updated
The living parts of the system are explicit: loading, icon style semantics, and mechanical conformance are rules agents can execute.
Spinner-first loading
Normal app loading uses one centered CircularProgress; skeletons stay reserved for admin density.
Spinner first for normal app loading.
Icon style semantics
Normal icons are commands, outlined icons are inactive or alternate state, filled icons mean selected or owned state.
Conformance gate
The lint path rejects raw values, raw buttons, raw icon sets, and literal values in HIG modules.
Topics
The public guidelines are organized from principles to reusable patterns to component contracts to input behavior.
Foundations
The non-negotiable design language: tokens, type, surfaces, motion, writing, accessibility, and brand discipline.
View area
Patterns
Reusable decisions for flows, feedback, navigation, loading, settings, and recovery.
View area
Components
The Socra primitive catalog. Product teams compose these; they do not create unowned replacements.
View area
Inputs
How keyboard, pointer, touch, gestures, and focus move through the same component contracts.
View area
Core Tokens
Primary accent
The only accent for the screen goal. Use it for one primary action, not for decoration.
Secondary action
Use for supporting action emphasis when contained primary would create two competing goals.
Neutral emphasis
Use for muted controls, utility chrome, and state that should not imply success, warning, or error.
Main canvas
Desktop application canvas and the default depth behind structured panes.
Base canvas
Deepest background, mobile sheet foundation, and full-screen immersive surfaces.
Raised card
Raised grouped content that has its own task boundary.
List surface
Dense panes, table regions, and repeated item containers.
Sidebar surface
Persistent navigation and structural rail surfaces.
Input surface
Editable fields and controls that receive user data.
Tooltip surface
Transient explanatory overlays that sit above the working plane.
Primary text
Essential labels, active values, and sentences required to complete the task.
Secondary text
Explanatory copy, metadata, and lower-priority information that remains readable.
Default text
The default foreground for content that inherits from a product surface.
Disabled text
Unavailable controls only. Do not use it to make optional content quiet.
Spacing scale
All distances, insets, row gaps, and layout rhythm. Never write a raw size.
Standard radius
Default component and card corner treatment unless the primitive owns a stronger contract.
Elevation
Depth and separation by layer. Never write a raw shadow string.
Motion duration
Default duration for state transitions, always disabled or shortened for reduced motion.
Motion easing
Default easing for changes that are neither entering nor leaving the screen.
Drawer layer
Navigation drawers and structural overlays. Never write a raw layer number.
Dialog layer
Blocking decisions and focused workflows above the app shell.
Heading type
Page and section titles that define scan structure.
Body type
Dense guidance, metadata, and documentation body copy.