SearchApi Design System

Foundations

SearchApi Design System

Every component in this browser is the one the site renders. Nothing here is a drawing of a component, and nothing here is a copy of a token — the pages under this section read design/design-tokens.json at render time, which is the same file the rest of the pipeline is generated from:

design/design-tokens.json      the single source of truth
  ├─ design/generate_tokens.rb        → web/app/assets/tailwind/tokens.css
  ├─ design/build_library.rb          → design/library/*.html
  ├─ design/generate_brand_icons.rb   → web/app/components/brand_icon_paths.rb
  └─ these pages                        read it, and copy none of it

That is the point of the arrangement. A foundations page that transcribed its values would be a second description of them and the first one able to go stale.

What is in here

Components — every ViewComponent the application defines, one preview each, with the variants and states it actually models. The set is pinned by test/conformance/component_inventory_test.rb, which asserts a strict 1:1 between the classes the app defines and the catalog in design/lib/components.rb.

Foundations — colour, type, radius and shadow, motion, and the seven data states the playground can be in.

Two switches, and they are not the same one

The theme control in the toolbar sets the class on the preview's <html>: absent for system, light or dark for the two explicit states. That is exactly how the application does it — there is no dark: variant anywhere in the codebase, because the token indirection flips every semantic colour already. test/conformance/token_conformance_test.rb fails a dark: on sight.

ThemeControlComponent under Chrome is the site's own control, and pressing it really does POST to /theme. It changes the cookie, not this frame.

Rules a component here obeys

  • A component takes a meaning, never a colour. BadgeComponent has no role: parameter and will not grow one; a new meaning is an entry in Design::Components::MEANINGS, decided once in a place both the library card and the application read.
  • Utility classes are written out in full, never interpolated. Tailwind reads literal strings out of source, so bg-#{role} is a class it never emits and a component that ships unstyled.
  • A component renders nothing rather than something untrue. PagerComponent draws no pager for an engine that cannot paginate, and has a "Renders nothing" scenario saying so; JsonLinesComponent offers a drill-in link only where TokenHandoff proves another engine consumes the value.