UI standards
These rules govern how UI is built in Baseleg. They exist to prevent styling drift, reduce decision fatigue, and keep the product looking and behaving consistently.
Core rules
1. Use @baseleg/ui first
Before writing any custom UI, check whether packages/ui already has a component that covers the need. Duplicate components are the primary source of styling drift.
If a component is missing from @baseleg/ui and is likely to be reused, add it there — do not build it inline in a page.
2. Use tokens for all visual values
Every colour, spacing value, border radius, and shadow must reference a design token. No hardcoded hex values or pixel values are permitted in component or page code.
See Design tokens for the full token reference.
<!-- Correct -->
<div class="rounded-lg border border-slate-200 bg-white p-4 text-sm text-slate-700">
<!-- Wrong — hardcoded values -->
<div style="border-radius: 8px; border: 1px solid #e2e8f0; background: #fff; padding: 16px; font-size: 14px; color: #334155;">3. Handle all four view states
Every view that loads data must implement all four states:
| State | Requirement |
|---|---|
| Loading | Skeleton or spinner; never show a blank page |
| Empty | Explain what is missing and what to do next |
| Error | Explain what went wrong; offer a retry where possible |
| Success | The normal data view |
See the empty / loading / error pattern for implementation guidance.
4. No unreviewed external libraries
Do not add a new component library (e.g. Headless UI, Radix, shadcn/ui, Flowbite) without first raising an ADR. The decision must be reviewed because it affects bundle size, accessibility, token compatibility, and long-term maintenance.
5. Document new reusable components
When a new reusable component is added to @baseleg/ui, a corresponding page must be created in docs/ux/components/<name>.md. See the component documentation guide.
Accessibility requirements
- All interactive elements must show a visible focus ring (see Design tokens — focus rings).
<img>elements must have descriptivealtattributes. Decorative images usealt="".- Colour alone must not be the sole indicator of state — pair colour with text or icon.
- Interactive elements must have a minimum touch target of 44×44px.
Responsive design
Baseleg targets desktop-first use (operations staff at a desk), but views must not break on tablet-sized screens. The minimum tested viewport is 768px wide.
Use Tailwind’s sm: prefix for simple responsive adjustments. Avoid xs: or sub-768px breakpoints unless explicitly required.