Refract UX
Production tokens, controls, and patterns in one inspectable surface.
Foundations
Use semantic roles such as --surface-base and --text-primary in component CSS. Primitive color values stay in the token layer and are shown here for inspection.
CSS API--surface-*--text-*--accent-*--border-*
surface-canvassurface-basesurface-subtlesurface-strongaccent-primaryborder-defaultThese are the only literal color values. Components consume the semantic roles above instead.
--color-white--color-black--color-stone-25--color-stone-50--color-stone-100--color-stone-200--color-stone-400--color-stone-600--color-stone-800--color-slate-100--color-slate-300--color-slate-700--color-slate-800--color-slate-900--color-blue-300--color-blue-500--color-blue-700--color-cyan-400--color-violet-400--color-lime-400--color-mint-400--color-orange-400--color-pink-400--color-teal-300--color-green-500--color-amber-500--color-rose-500--color-paper-25--color-paper-50--color-paper-100--color-paper-200--color-paper-400--color-paper-700--color-paper-900Square is the default. Only direct actions and intentionally elevated moments gain rounding.
--space-1--space-3--space-5--space-8--radius-none--radius-interactive--radius-emphasis--radius-dialogSemantic HTML + CSS.ui-kickerh1h2h3
Top mini all-caps header
Body text is optimized for readable product content, not decoration.
Square: cards, fields, tables, panels, documents.
Round: every direct action, navigation item, and icon control.
Medium round: only elevated cards and dialogs.
Actions
UiButton emits a button for actions and an a when it receives href. Variants only communicate priority; they do not create product-specific button styles.
UiButton.astro.ui-button.ui-button--{variant}.ui-button--{size}
UiButton.astro.ui-button--inverse.ui-button--outline-inverse
UiIconButton.astro + UiTextLink.astro.ui-icon-button.ui-text-link
Inputs
Text fields are square document surfaces. Only controls that are directly pressed or toggled use the interactive round token.
UiSelect.astro + CSS primitives.ui-field.ui-select.ui-input.ui-textarea.ui-checkbox.ui-switch
Website
These are the concrete shared building blocks used by the public site: persistent header navigation, LightField hero layers, optional prompts, carousel controls, and the two-band footer.
RefractHeader.astro + HeaderLink.astro.site-header.site-brand.site-header__link
LightField hero
Text sits directly on the field. Home centers it; other pages use the top-left or left-center alignment.
Content stage
Blur begins around three-fifths down.Explore the workLightFieldHero.astro + LightFieldContent.astro + UiTextLink.astro.lightfield-hero.lightfield.lightfield-content.ui-text-link
SocialLinks.astro + LanguagePicker.astro + LanguageSuggestion.astro + Analytics.astro.social-link.footer-language.language-suggestion.analytics-consent
SnapCarousel.astro + RefractFooter.astro.snap-carousel.site-footer.footer-social-band.footer-main
Surfaces
Cards are independent content containers. Use a link card only when the whole region navigates; reserve the medium round token and stronger shadow for deliberate modal interruptions.
CSS primitives.ui-card.ui-card--subtle.ui-card--interactive.ui-dialog
Square, bordered, and intentionally quiet.
For a grouped region on the same canvas.
Hover confirms it is a destination.
Dialog
Medium rounding and stronger elevation mark a deliberate interruption.
Content
Tables use semantic table markup. Badges communicate compact status and must not be the only way a state is conveyed.
CSS primitives.ui-table.ui-badge.ui-badge--accent.ui-badge--positive
| Document | Status | Updated |
|---|---|---|
| Design system guide | Draft | Today |
| Reader shortcuts | Published | Yesterday |
Feedback
Use an alert for a user-visible condition, a progress bar for a measurable task, and badges for short statuses. None require a product-specific feedback component.
CSS primitives + controls.ui-alert.ui-alert__icon.ui-progress.ui-badge.ui-button.ui-icon-button
Reconnect to continue uploading reading progress.