Skip to content
UI Design Principles
AutoXXS (320px)XS (375px)SM (640px)MD (768px)LG (1024px)XL (1280px)XXL (1536px)
SketchMaterialiOSTamagui
DataInjectionKeyPatternsServiceTransactionProcessResearchProductQualityPerformanceSpecDomainFunctionTechnologyArchitectureConfigMiddlewareDataDatabaseDrizzleMigrationModelop-sqliteSchemaSQLState ManagementDraftKeystoneMergePatchPatchesPersistenceReactiveRedoStoreUndoTestingDeviceFactoryIsolationTypeScriptZodTopicsCommunicationBidsNVCDesignDesign ImplicationsEducationPedagogyFoundationsPsychologyAttachmentFloodingRelatingAuthentic RelatingUIEditorReact Native

UI Design Principles

Fragment convention UI Design Principles
tags
conventionuidsl

These apply to every surface document regardless of which loop is active.

Component Semantics

Use the most semantically precise component available. Do not use stack + text where list or table is appropriate. Do not use card + stack where modal or accordion solves the layout problem natively.

Prefer components in this order: semantic container first (tabs, accordion, stepper, modal) → layout (stack, row, grid) → generic (card, section).

Accessibility by Default

  • Every input, select, checkbox, and slider must have a label attribute.
  • Every primary button must have a label or text content.
  • Navigation link items must have a label attribute.
  • Interactive regions (tabs, accordions, steppers) must have enough structure for a screen reader to follow — label every panel, step, and tab.
  • Do not use placeholder as a substitute for real content in interactive areas. Reserve placeholder for genuinely unknown visual elements.

Feature Linkage

Every \{% surface %\} tag must have a for attribute pointing to a valid qualified id (feature, flow, or action). Do not create a surface without a corresponding feature or flow to link it to.

Verify the linked document exists before writing:

get_document("feature/{id}")

Layout Hierarchy

  • One section or nav per screen — this is the outermost shell.
  • card and modal group related content within a section.
  • stack and row handle spacing and alignment within cards.
  • Do not nest section inside section or card inside card without a clear rationale.

Placeholder Discipline

Use placeholder for visual elements that are not yet designed, not for laziness. Every placeholder must have a type and a label. At status: review, no placeholder should remain without a comment explaining why it is deferred.