Principles
Core design principles and rules for building with the design system.Design Philosophy #
A design system that prioritizes consistency, adaptability, and developer experience. Every decision flows from a few core ideas:
- Components over primitives: use components for everything they cover before reaching for raw HTML
- Semantic tokens over hardcoded values: colors, spacing, and radii are named by purpose, not appearance
- Theme-agnostic code: your app code never references specific colors or measurements, so themes and dark mode work automatically
- Open internals: every primitive is exported and composable, so you can build on top of it without fighting it
Rules #
- Use components for everything they cover
- Layout is frame-first: pick the shell and budget regions before writing content (see
astryx-svelte docs layout) - Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups
- StyleX or Tailwind for custom styling; both are first-class (see
astryx-svelte docs styling) - Semantic tokens, not hardcoded values (see
astryx-svelte docs tokens) - CSS custom properties for colors, not hex values
- Form inputs are controlled: bind with
bind:value(or passvalueand anonchangehandler) - Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider
Styling Approach #
The design system supports multiple styling approaches. Every component accepts an xstyle prop for StyleX style overrides authored with stylex.create() in a sibling .stylex.ts module. For layout and wrapper styling outside of components, use StyleX, scoped <style> blocks, or Tailwind utilities; all resolve to the same design tokens.
See astryx-svelte docs styling for the complete guide with examples.
Anti-Patterns #
| Guidance | Practices |
|---|---|
| Don't | Inline styles on raw elements. Use xstyle on components |
| Don't | Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface) |
| Don't | Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities |
| Don't | Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider |
| Don't | Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see astryx-svelte docs layout) |
| Don't | Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status |
| Don't | Inventing props. Read component docs first |
Design Tokens #
The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run astryx-svelte docs tokens for the full reference with all values.