Building a page with this design system

Everything on this page is reachable over plain HTTP. You do not need the design-system repo, a Rails install, or the bin/ds CLI.

Download the artifacts raw. They are code, not prose — a fetch tool that summarises pages will hand you class names that do not exist (measured: 8 of 9 shell class names in one summarised fetch were fabrications, and the prototype built on them was thrown away). Use curl -o, read the saved file, grep it when in doubt. The reference doc is ~170 KB; if you received a few neat paragraphs, you are reading a paraphrase, not the file.

1. Start from the frame, never rebuild it

The application shell — rail, drawers, topbar, and the exact wrapper classes around your content — is the one part with no component to copy, and it is where hand-built pages go wrong.

curl -o page.html "https://designsaplus.com/cdn/shell.html?variant=school"

variant is school, la or mat. What comes back is a complete, styled, fillable page: the real navigation rendered from the same partials this Lookbook renders, stylesheet and JS linked as absolute URLs so the file still works once you save it, and the frame rules in a comment at the top.

Put your content inside .tw-container-fluid.tw-page-container. Change nothing above it. Two rules that frame keeps:

• the element carrying .tw-sidebar-topbar-content-offset takes only its variant's classes. A tw:p-* or tw:max-w-* there pins the page into a narrow column with a dead gutter — the most visible defect in hand-built prototypes.
• page content lives inside .tw-container-fluid.tw-page-container, which owns the spacing and the bottom clearance.

2. Lift component markup, don't infer it from class names

Every component's page in this Lookbook is the source of truth for how its parts nest — and nesting is most of what makes a component look like itself. Fetch the preview and copy the element you need:

curl -L "https://designsaplus.com/lookbook/preview/components/note/comprehensive"
curl -L "https://designsaplus.com/lookbook/preview/patterns/page_header/comprehensive"

Preview URLs spell multi-word names with underscores (stat_tile, page_header); the hyphenated spelling the docs use redirects there, so pass -L. A 404 means the scenario name is wrong (the default is comprehensive), not that the markup is unreachable.

Four separate authors once rebuilt .tw-note from its class list and all four put the icon in the wrong element; the wrong shape then reached three prototypes and the public reference doc. Treat the rendered preview as truth and the class tables as the check.

3. Inherit from the screen your feature extends

A screen that already exists is better than a new one that nearly does. Browse Projects in the sidebar — those are real screens, and one of them is usually closer to your ticket than a blank page.

Better still, ask, and then fetch the answer. When your feature extends an existing area, that area's conventions are not yours to redesign:

curl -s "https://designsaplus.com/cdn/ds?cmd=pages"      # every real screen
curl -s "https://designsaplus.com/cdn/ds?cmd=blocks"     # best example per screen type
curl -L  "https://designsaplus.com/lookbook/preview/projects/<feature>/<scenario>"

Match the sibling screen's toolbar slot order, its filter controls, its pagination and its table affordances. A MAT+ in-year review list built without this step used plain selects where its sibling uses filter dropdowns, shipped no pagination, dropped the sortable/check/action cells, and added a five-tile KPI strip the sibling does not have — four conventions re-decided by accident.

/cdn/ds is this repo's CLI over HTTP: list, blocks, pages, component, pattern, template, search, gotchas, parity. Add --html to component or pattern for real markup, and run ?cmd=gotchas+<name> before building with anything unfamiliar — it lists the traps that have already cost someone a day.

4. Icons: link ours, not a public Font Awesome CDN

<link rel="stylesheet" href="https://designsaplus.com/cdn/fontawesome.css">

The rail is drawn in fa-light, a Font Awesome Pro weight, and the free CDNs ship no Light face — against them those glyphs render as nothing, not as a substitute glyph. /cdn/shell.html already links the line above.

If a page comes out in the wrong typeface with square boxes for every icon, it is a browser refusing a cross-origin font, not a missing class. Fonts are fetched under CORS even when the stylesheet naming them is not, so a font served without Access-Control-Allow-Origin fails silently — the text drops to a system face and the icons become tofu. Everything under https://designsaplus.com/ sends that header; a copy on a host that doesn't will not.

5. Check your work before you deliver it

curl -s --data-binary @page.html "https://designsaplus.com/cdn/validate"

The same linter CI runs on this repo's own pages — dead Bootstrap-style classes, invented tw- classes, retired variants, inline styles, raw hex, shell-frame assembly mistakes — over HTTP, so a build outside the repo can be checked too. ?format=json for machine-readable findings. A clean report proves the classes exist, not that the screen is right: still open the file and look at it.

Two checks are aimed squarely at hand-built pages, because a bespoke frame used to pass clean (every rule keyed on a tw- name, so anything invented under your own prefix was invisible):

• frame-not-inherited — a whole page using the design system with no shell frame at all. Fix it with step 1, not with a class.
• reimplemented-component — a page that defines its own .x-sidebar, .x-drawer, .x-modal or .x-backdrop while using none of ours. A rebuilt container loses the controller, the ARIA and the keyboard contract, and none of that is visible in a screenshot.

It also prints a DS coverage ratio for a whole-document file — how many design-system classes your page wears against how many of your own. More bespoke names than DS ones means the product was rebuilt rather than used, whatever the finding count says.

6. Everything else, over HTTP

All on https://designsaplus.com.

Working inside the design-system repo instead? bin/ds template shell --html and bin/ds component <name> --html do jobs 1 and 2 offline, bin/ds validate <file> lints the result, and ai-docs/prototype-from-ticket-workflow.md is the long-form method this page summarises.