{"node":{"id":"98841826-13b8-4843-ba74-fd26981525db","handle":"9884","type":"note","authorName":"Vincent Yeung","intent":"learning","title":"Drawer 5: Building it","aiSummary":null,"content":"**Open it when:** you're choosing a component library, writing the DESIGN.md, or setting up a page that runs with no build step.\n\n## What we know\n\n### The DESIGN.md\n\n**What it is**\n- One markdown file that holds a design system. Tokens (named values for colour, type, corners, spacing) sit at the top in YAML. Written rules sit below. [awesome-design-md]\n- awesome-design-md credits the idea to Google Stitch. It needs no Figma export, schema or special tools. [awesome-design-md]\n- AGENTS.md tells an agent how to build. DESIGN.md tells it how the result should look. [awesome-design-md]\n- Our build: write the look down in one DESIGN.md. Colours, type, spacing and components first, then layout, motion, voice, and what to do and not do. Every later change reads it, so the look doesn't drift. [our build]\n\n**What goes in it**\n- impeccable's `document` command writes it in Google's format: tokens up top, then up to eight sections in a fixed order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. [impeccable]\n- The 74 awesome-design-md files with tokens up top use those same eight sections. Many add Responsive Behavior (61 files), an Iteration Guide (50) and Known Gaps (43). [awesome-design-md]\n- Leave out a section that doesn't apply. Don't invent rules to fill it. [impeccable]\n- The tokens are the rule. The written part explains how to apply them. [impeccable]\n- Build each component from token names in braces. Never type a raw hex colour into a component. [awesome-design-md]\n- Give colours descriptive names (\"Deep Muted Teal-Navy\", not \"blue-800\"). [impeccable]\n- Change one component at a time. Add variants as separate entries. [awesome-design-md]\n- 34 awesome-design-md files say to run `npx @google/design.md lint DESIGN.md` after edits. Nobody here has run it. [awesome-design-md]\n\n**When to write it: the sources clash**\n- Our build: write DESIGN.md first, so every later change reads it. A skill for a new site should make DESIGN.md the first thing it writes. [our build]\n- impeccable: for a new look, write DESIGN.md at the finish, from what was built. A rulebook written before the build gets defended against reality. [impeccable]\n- impeccable also says a missing DESIGN.md doesn't make a project new. A look already in the code counts. [impeccable]\n- Never overwrite an existing DESIGN.md without asking. Offer refresh, overwrite or merge. [impeccable]\n\n### Component libraries\n\n- Use a component for anything the library covers before reaching for raw HTML. [Astryx]\n- Name tokens by purpose, not by value or looks. [Astryx; impeccable]\n- Read the component docs before using a component. Don't invent props. [Astryx]\n- Astryx's rules for agents: start every page from a template, no raw divs, no inline `style={{}}`, tokens instead of made-up values. [Astryx]\n- Restyle without forking: pass `className` with Tailwind, CSS modules or plain CSS. `swizzle` copies a component's source into your project to own. [Astryx]\n- impeccable: in a committed look, rebuild nav, buttons, inputs and links in that look. A stock component left in is a lapse. [impeccable]\n- Our build: Astryx reads clean and systematic, so it needs a lot of theming to feel warm. [our build]\n- Pull something into the shared system only when it's used three or more times for the same purpose. Two buttons that look alike but do different jobs stay separate. Early abstraction is worse than repetition. [impeccable]\n- Match the code to the look. A maximal design needs elaborate code and effects. A minimal one needs restraint and precise spacing and type. [frontend-design]\n\n### Pages with no build step\n\n- React 19 has no single-file build any more, so the old unpkg link fails. [our build; Astryx]\n- For React without a build step, load it from esm.sh with an import map, and write the markup with htm. [our build]\n- Astryx gives the same route: an import map and esm.sh. `npx @astryxdesign/cli template --cdn` writes a no-build HTML page pinned to your installed version. [Astryx]\n- On an Astryx no-build page, set `data-astryx-theme` on `<html>`, or the theme won't apply. Add the font link yourself. [Astryx]\n- With a bundler, Astryx needs no build plugin: three CSS imports (`reset.css`, then `astryx.css`, then the theme's `theme.css`, in that order) plus a theme wrapper. Recipes exist for Next.js and Vite. [Astryx]\n- For plain HTML, keep motion to CSS. [frontend-design]\n- Astryx's layered pop-ups need recent browsers: CSS anchor positioning (Baseline 2026), the Popover API and `light-dark()`. In older supported browsers, pop-ups open but aren't positioned. [Astryx]\n\n### Working with agents while you build\n\n- Look at the real rendered page before editing. Check it at the sizes it ships at. Fix everything one look shows before looking again. [impeccable]\n- If more than one agent takes screenshots at once, give each its own browser. Sharing one, they take each other's pages. Each one checks the address before it takes a shot. [our build]\n- Every requirement in the brief must be on the page and findable within seconds. [impeccable]\n- Never copy the written direction (the brief) into code or anything sent to the browser. [impeccable]\n\n## Tools in this drawer\n- **Tool: DESIGN.md, the look written down.** Pick it once the direction is chosen, so every later change reads the same rules.\n- **Tool: borrow from a brand (awesome-design-md).** Pick it when you want a finished DESIGN.md to start from or learn from.\n- **Tool: Astryx for agents (CLI and MCP server).** Pick it when an agent builds on Astryx and must look things up instead of guessing.\n- **Tool: Astryx theming.** Pick it to make Astryx match your DESIGN.md.\n- **Tool: Astryx forms.** Pick it when the site needs real forms on React.","capturedAt":"2026-10-29T09:31:21.979Z","createdAt":"2026-10-29T09:31:21.979Z","updatedAt":"2026-11-06T04:43:57.016Z","spanId":null,"contributor":null,"audiences":[{"kind":"public","createdAt":"2026-11-06T04:27:11.279Z"}],"fingerprint":"5ed8da87f333ea517c55f8b050ca46d893bb1b907cb1151fa7feef68cc0cccdf","revisionNo":"3","structureHash":"f4b3deab8497b5b9ae3a7026a8ae25e2d882e23aeece6ec80513f14acd2b4221","page":"https://lattris.com/by/b/memories/98841826-13b8-4843-ba74-fd26981525db"},"links":[{"direction":"out","verb":"references","reason":"Pick it when you want a finished DESIGN.md to start from or learn from.","hash":"37827cf979089c0fa68217c235bab6ccb74f199eeee126f3a31fb12f2990b46c","node":{"id":"335daa15-76fb-4e73-bd51-41e8672d0b9e","handle":"335d","type":"note","title":"Tool: borrow from a brand (awesome-design-md)","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/335daa15-76fb-4e73-bd51-41e8672d0b9e?links=1","fingerprint":"aec6259a235f1b6acac87dd41abb270618663023f41b0ec4bedcd22f334b42e5","revisionNo":"1","structureHash":"d9cd5257f1be680a4cadc768e2687fd4c9aaf8e1efb5f399f68a799380e56adc","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/335daa15-76fb-4e73-bd51-41e8672d0b9e"}},{"direction":"out","verb":"references","reason":"Pick it once the direction is chosen, so every later change reads the same rules.","hash":"99c60e91bb5cc2bef5e8bee26a3597a6ef7bb5add9aeb8bdfba66f33a5e06f5d","node":{"id":"5e1fb5f2-54ab-4ad2-a5bc-f016a21ba0d7","handle":"5e1f","type":"note","title":"Tool: DESIGN.md, the look written down","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/5e1fb5f2-54ab-4ad2-a5bc-f016a21ba0d7?links=1","fingerprint":"1fddcc701e7b8ee8581304eac00f9d21309205010c6f6cf36ed613071c24efc4","revisionNo":"1","structureHash":"b776ac85e0e71758fce3ccfe1e1c7c30221b2684bf47375df56b75778c3580b7","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/5e1fb5f2-54ab-4ad2-a5bc-f016a21ba0d7"}},{"direction":"out","verb":"references","reason":"Follow back to pick a different drawer.","hash":"e02cac82ad4100e17d635b7e946faca82ab9b3df2081b34d6d20374e1bc3eeed","node":{"id":"5f8b457d-b87a-4e61-9af2-3008deaf37a9","handle":"5f8b","type":"note","title":"Front-end design: the toolbox","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/5f8b457d-b87a-4e61-9af2-3008deaf37a9?links=1","fingerprint":"49e1c7f41f22c466c7ef1a993cab80b6dcbedab4552d2ac684133d60dea7e60b","revisionNo":"2","structureHash":"64df670c7bd82572e0ad9b2e06b8829d3b2e509be134591c04ea1fa281fca3ef","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/5f8b457d-b87a-4e61-9af2-3008deaf37a9"}},{"direction":"out","verb":"references","reason":"Pick it when the site needs real forms on React.","hash":"60bfa500abcd10e58af6f876b9eb5f870687762c0598ed9c92708925885c1f43","node":{"id":"652bb4cd-0dc8-432d-b2c5-f571a5e308d2","handle":"652b","type":"note","title":"Tool: Astryx forms","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/652bb4cd-0dc8-432d-b2c5-f571a5e308d2?links=1","fingerprint":"100abb4f344196d894688c0c46799e4f88d89b136b3ee53ff8f205f218929e35","revisionNo":"1","structureHash":"706bfddf88472bf50997bb2c0db60b9a8a8f2d11bc773b3ca071064762bd373e","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/652bb4cd-0dc8-432d-b2c5-f571a5e308d2"}},{"direction":"out","verb":"references","reason":"Pick it to make Astryx match your DESIGN.md.","hash":"ad9047432e795221220e2d18f4b37cc4ca91d18b770070d67f051fca665b83af","node":{"id":"803f6d6d-0ecf-4a9c-8438-26d25e3f73b7","handle":"803f","type":"note","title":"Tool: Astryx theming","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/803f6d6d-0ecf-4a9c-8438-26d25e3f73b7?links=1","fingerprint":"dc9053afefddf3d2523af49f2dc7652c9ce9955adc55647354c3fbbbee347beb","revisionNo":"1","structureHash":"f8aecdf69fc5b9e2c44844d6a75246bb7995d69e7545fae9599379f4f58453e9","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/803f6d6d-0ecf-4a9c-8438-26d25e3f73b7"}},{"direction":"out","verb":"references","reason":"Follow when a line marked [our build] needs its full context.","hash":"3cfc59ad5adeded06f58c2d1bdd6d1be1db4d64934df5166eece040a824c7c3e","node":{"id":"ec50a07f-f1ee-4008-b3ce-b7e1a847d706","handle":"ec50","type":"note","title":"Pattern: building a website with AI","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/ec50a07f-f1ee-4008-b3ce-b7e1a847d706?links=1","fingerprint":"62d9975e4cd521f59b3f3e71719dbcae5835d307e28597ea0104247bb6721bb2","revisionNo":"1","structureHash":"e63b54c083aa93ec272c5d03a5b587824c3c5a78373b8839600f59268a5f2083","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/ec50a07f-f1ee-4008-b3ce-b7e1a847d706"}},{"direction":"out","verb":"references","reason":"Pick it when an agent builds on Astryx and must look things up instead of guessing.","hash":"483074ce6addd3b155d479bdd10deb8551fb46eb10215b92ac014323824473f1","node":{"id":"ff94b18f-43e0-4c83-a456-25cc433dbfd7","handle":"ff94","type":"note","title":"Tool: Astryx for agents (CLI and MCP server)","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/ff94b18f-43e0-4c83-a456-25cc433dbfd7?links=1","fingerprint":"52ba88470bbc1372c6f33fff25d588124335bc2775fe4cde42e7e883e8d76896","revisionNo":"1","structureHash":"fca111ae4ffb0caf03fabbc5422e51fd57b197cf8653f02d652a50916226c131","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/ff94b18f-43e0-4c83-a456-25cc433dbfd7"}},{"direction":"in","verb":"references","reason":"Follow for the dispute on whether to write DESIGN.md first or last.","hash":"9a7cfc7904b02dfa013f05b7030d4aec614fd84aead7161539b9295676266eb9","node":{"id":"5e1fb5f2-54ab-4ad2-a5bc-f016a21ba0d7","handle":"5e1f","type":"note","title":"Tool: DESIGN.md, the look written down","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/5e1fb5f2-54ab-4ad2-a5bc-f016a21ba0d7?links=1","fingerprint":"1fddcc701e7b8ee8581304eac00f9d21309205010c6f6cf36ed613071c24efc4","revisionNo":"1","structureHash":"b776ac85e0e71758fce3ccfe1e1c7c30221b2684bf47375df56b75778c3580b7","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/5e1fb5f2-54ab-4ad2-a5bc-f016a21ba0d7"}},{"direction":"in","verb":"references","reason":"Open it when you pick a component library, write the DESIGN.md, or set up a page with no build step.","hash":"c9f4450fb2a3c49802eaf1b60f60189048739d6bb3f1b6e8d0ab8d512f8e79cd","node":{"id":"5f8b457d-b87a-4e61-9af2-3008deaf37a9","handle":"5f8b","type":"note","title":"Front-end design: the toolbox","aiSummary":null,"erased":false,"href":"https://lattris.com/api/lattris/by/b/memories/5f8b457d-b87a-4e61-9af2-3008deaf37a9?links=1","fingerprint":"49e1c7f41f22c466c7ef1a993cab80b6dcbedab4552d2ac684133d60dea7e60b","revisionNo":"2","structureHash":"64df670c7bd82572e0ad9b2e06b8829d3b2e509be134591c04ea1fa281fca3ef","intent":"learning","authorName":"Vincent Yeung","page":"https://lattris.com/by/b/memories/5f8b457d-b87a-4e61-9af2-3008deaf37a9"}}],"dictionary":{"lattris":"A personal knowledge base — how a person captures what they know as linked blocks they own and control. To understand how this knowledge base works: https://lattris.com/by/4/memories/lattris-a-memory-store-for-your-life-43ff","intents":"Every block can carry an intent — a label for how far you have taken the idea. The scale runs from noticing something to acting on it: noticed (something caught your attention), learning (you are working it out), truth (you are saying this is how things are), decision (you chose a course), action (you did it). Recipe sits outside that scale — it is not a stronger claim, it is a different kind of thing: a procedure, a how-to, a set of steps that ties other knowledge together. Intent is optional — leaving it blank just means you have not labelled it yet."},"instructions_to_ai":"This is knowledge from a personal knowledge base. Read it and consider how it's relevant to what the person you're talking to needs. Follow the linked blocks to explore further related topics if it might be useful to the user; open each at its page address. Start by letting the user know what this is about and how it may be relevant to them."}