Design Cards Reference

This page is the card dictionary of the swift-web design resources: all 20 cards shown full-width, each with a note on what it is and how to use it while designing. The card HTML is the same pipeline output as the design systems inside Claude Design / Open Design (all derived from framework source) — what you see here is what the AI references once you pick the swift-web design system in either tool, and it is also exactly how the components render in production.

How to use this page

  • Browse before designing (form dictionary): know which component forms the framework already ships, and compose from them first — implementation maps one-to-one, no "translation" by the frontend.
  • Call cards by name when drafting: card names are the shared language. In Claude Design / Open Design, say "lay out a row of movie covers in the SwRail form" or "use the SwModal structure for the dialog" — those cards are in the design system the AI reads, so it lands precisely.
  • Compare during review: when a draft or a live page doesn't match a card, the card wins — report it to the maintainers (cards are derived from source code; they don't lie).

Two labeling conventions:

  • "Reference implementation (not built into the framework)": wherever this appears (e.g. colored button variants, the visual style of form inputs), the framework deliberately does not ship that styling — the card shows a recommended treatment using semantic tokens. Use it as-is or redesign it, as long as you stay inside the token vocabulary.
  • Want to change a card itself (you think a default form is wrong): cards are derived artifacts, never hand-edited — raise it with the framework maintainers per Governance, discipline #2.

Tokens (3 cards)

Colors · semantic color tokens

Every semantic color variable with its name and actual values (light and dark). Any color in a draft should trace back to a name on this card — rebranding changes these values, which is why "color by name" drafts are inherently deliverable. The three text tiers (--foreground / --foreground-soft / --muted-foreground) can be compared here too.

Typography · type tokens

Font stacks (CJK-first system fonts, no webfont), the size scale, link and focus styles. Body line-height ~1.5, headings at weight 600 — the "why type looks the way it does" card.

Shape & Layout · radius / shadows / layout

The unified 0.5rem radius, three shadow tiers (sm/md/lg), 60px nav height, 1920px content max-width. Why cards, buttons and modals share the same corner radius — this is the source.

Basic components (9 cards)

SwButton

Primary / secondary / ghost forms plus loading / disabled states. Hover is uniformly "one step darker" (a house rule — no invented hover colors). The colored variants are a reference implementation — feel free to redesign within the tokens.

SwSegmented

Single-select for options that are few and should all stay visible (e.g. "Latest / Hottest / Top rated"). Complements SwSelect: use the dropdown when options are many or horizontal space is tight.

SwSelect

Dropdown with single / multi select, groups, and clearing. Designing a filter bar? If there are ≤5 important options → SwSegmented; more → this card.

SwModal

Centered panel over a dimmed overlay, with a title / body / actions structure. Focus management and Esc-to-close come built in — design only needs to care about the panel content.

SwToast

Stacked short-lived feedback, status-colored via semantic tokens (success green / error red / warning gold). Don't design decision-requiring content as a toast (use a modal) — toasts auto-dismiss.

SwPagination

Numbered paging with the current page in the primary color. For "replace-the-screen" lists; for load-more streams see SwGallery.

SwBreadcrumb

Hierarchy navigation (home / category / detail). Middle nodes are real links, which helps SEO — including it on detail pages has measurable indexing value.

SwFormField

The label / input / error structure of a form field, with a destructive-red error state. The input's visual style is a reference implementation — restyle forms freely, but keep the field structure.

SwTable

Admin-console data table: a baseline visual of tinted header cells and row hairlines, with built-in column-sort arrows, row-selection checkboxes, zebra stripes, compact density and a sticky header. Reach for this card first on admin list pages; pagination and filters stay outside the table — compose SwPagination / SwSegmented at the page level.

Content components (8 cards)

SwImage

The carrier for all content images (covers / banners / avatars): ratio-reserved placeholding (no layout jump while loading) and a failure fallback state. Just decide the aspect ratio when designing cover cards (2:3 is the usual portrait for video sites).

SwRail

A card row that scrolls horizontally when one row can't fit (the workhorse of homepage floors). Card size is the designer's call; desktops get hover arrows, mobile swipes. Versus the carousel: a Rail slides many cards side by side, a Carousel switches one full-width slide at a time.

SwCarousel

The full-width rotating banner: autoplay, seamless loop, dot / thumbnail indicators. The homepage hero slot is this.

SwGallery

Equal-height grid with "load more" (the workhorse of library / full-list pages). Column count adapts to viewport width — design a single card's form and you're done.

SwAd family

Twelve ad-slot forms: banner / MREC / icon grid / text link / marquee / native in-feed / side floating / splash / popup / video preroll / pause ad, plus the compliance badge. Check this card first when designing an ad slot — each form has different exposure-tracking semantics, and the data is only right when the form is.

SwVideoPlayer

The video player: control bar / danmaku / preroll & pause-ad slots. Player pages are laid out around it; the player's internals don't need redrawing.

SwUpload family

Button and drop-zone forms for image / video / generic file upload, including in-progress states. Used on UGC submission pages.

SwEditor

A Tiptap-based rich text editor: toolbar / @mentions / #topics / emoji / media insertion. The input area of comment sections and post pages.

Download & import