# NachoDS
Every page of the system at version 0.1.0, in one file. Each page begins with its title and names its source URL.
---
# Color
*Brand*
Every color is a token. Pages and components read the custom property, never the value, so changing one token recolors the whole system.
## Palette `#palette`
The table is written from `tokens.json` at build time.
| Token | Custom property | Value | Use |
| --- | --- | --- | --- |
| `color.ink` | `--color-ink` | `#17202a` | Primary text and high-emphasis marks. |
| `color.muted` | `--color-muted` | `#5d6876` | Secondary text on canvas, surface, and accent-soft. |
| `color.canvas` | `--color-canvas` | `#f5f7fa` | Page background. |
| `color.surface` | `--color-surface` | `#ffffff` | Raised panels, cards, and inputs; text on accent. |
| `color.line` | `--color-line` | `#dce1e8` | Rules and borders. |
| `color.accent` | `--color-accent` | `#2457d6` | Primary actions, links, and focus. |
| `color.accent-soft` | `--color-accent-soft` | `#e8efff` | Hover and selected backgrounds. |
## Grounds `#grounds`
Text color is chosen with the ground behind it. Each pairing below is the only one the system uses on that ground.
| Ground | Text | Secondary text | Use |
| --- | --- | --- | --- |
| Canvas | `--color-ink` | `--color-muted` | Page background |
| Surface | `--color-ink` | `--color-muted` | Panels, cards, and inputs |
| Accent soft | `--color-ink` | `--color-muted` | Hover and selected states |
| Accent | `--color-surface` | None | The primary action |
---
# Typography
*Brand*
A serif sets headings, a sans sets everything read at length, and a mono names tokens and code.
## Families `#families`
System fonts keep the starter fast, portable, and free of licensing assumptions.
| Token | Custom property | Value | Use |
| --- | --- | --- | --- |
| `font.sans` | `--font-sans` | `ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` | Body and interface text. |
| `font.serif` | `--font-serif` | `Georgia, "Times New Roman", serif` | Display headings. |
| `font.mono` | `--font-mono` | `"SFMono-Regular", Consolas, "Liberation Mono", monospace` | Token names and code. |
## Scale `#scale`
Six sizes, each with one job. Pick the role; never resize a role to make copy fit.
| Token | Custom property | Value | Use |
| --- | --- | --- | --- |
| `type.display` | `--type-display` | `clamp(2.25rem, 4.5vw, 3.5rem)` | Page titles. |
| `type.title` | `--type-title` | `clamp(1.5rem, 2.6vw, 2.125rem)` | Section headings. |
| `type.lead` | `--type-lead` | `1.125rem` | Introductory paragraphs. |
| `type.body` | `--type-body` | `1rem` | Reading text. |
| `type.small` | `--type-small` | `0.875rem` | Help text, captions, and table cells. |
| `type.label` | `--type-label` | `0.75rem` | Eyebrows, table headers, and tags. |
---
# The digital design system
*Digital DS · Foundations*
Paid ads, event banners, and promotional graphics for screens: everything placed in front of people who have not visited the website yet, and the banners that bring them to an event. It uses the Brand view's mark, type, and palette, and adds pixel sizes, safe areas, file weights, and the rules each placement brings. Meta and LinkedIn ads live in [Social DS](/social/).
## How this is organized `#organization`
Each page is one placement family. Every template on it ships in the three steps of the [template scale](/print/#scale), and one step runs across a campaign set, so the two units a person sees on the same day look related.
| Group | Covers |
| --- | --- |
| **Advertising** | The standard display units and the image and text assets for responsive campaigns. |
| **Events** | The webinar page hero, registration banner, and title slide, and the virtual background a speaker sits in front of. |
| **Owned Channels** | Email headers and signature banners, the website's promotional hero and strip, and business profile posts. |
## Every format `#formats`
The catalog is the `digital` group in `src/formats.json`. Previews, spec tables, and this list all read it, so a size changes in one place. Sizes and limits are the platforms' own; confirm them against current specifications before a campaign ships.
| Format | Size | Safe area | File | Max weight | Page | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| **Medium rectangle** | 300 × 250 px | 12 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Large rectangle** | 336 × 280 px | 12 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Leaderboard** | 728 × 90 px | 8 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Billboard** | 970 × 250 px | 14 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Half page** | 300 × 600 px | 14 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Wide skyscraper** | 160 × 600 px | 10 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Mobile banner** | 320 × 50 px | 6 px | PNG or JPG | 150 KB | Google Display Ads Planned | Too small for a disclaimer line; do not use it where one is required. |
| **Large mobile banner** | 320 × 100 px | 8 px | PNG or JPG | 150 KB | Google Display Ads Planned | |
| **Responsive landscape** | 1200 × 628 px | 60 px | JPG | 5 MB | Responsive & PMax Planned | The platform crops and overlays its own copy on responsive ads; keep text off the image. |
| **Responsive square** | 1200 × 1200 px | 60 px | JPG | 5 MB | Responsive & PMax Planned | The platform crops and overlays its own copy on responsive ads; keep text off the image. |
| **Webinar page hero** | 1920 × 600 px | 80 px | JPG, under 400 KB | | Webinar Banners Planned | The outer 240 px crop away on narrow screens; keep copy in the centre 1440 px. |
| **Registration banner** | 1200 × 628 px | 60 px | JPG or PNG | | Webinar Banners Planned | |
| **Webinar title slide** | 1920 × 1080 px | 96 px | PNG | | Webinar Banners Planned | |
| **Virtual background** | 1920 × 1080 px | 96 px | JPG or PNG, under 5 MB | | Virtual Backgrounds Planned | The speaker covers the central keep-clear region; the brand sits top left and the message upper right. |
| **Email header** | 1200 × 400 px | 48 px | JPG at 2×, displayed 600 × 200 | | Email Headers & Signatures Planned | |
| **Email signature banner** | 1200 × 200 px | 24 px | PNG at 2×, displayed 600 × 100 | | Email Headers & Signatures Planned | |
| **Website promo hero** | 1920 × 800 px | 96 px | WebP or JPG, under 300 KB | | Website Promos Planned | |
| **Website promo strip** | 1440 × 120 px | 24 px | HTML preferred; WebP fallback | | Website Promos Planned | |
| **Business profile post** | 1200 × 900 px | 60 px | JPG or PNG | | Google Business Profile Planned | |
## Previews `#previews`
A template is a canvas sized from the catalog and composed from the pieces in `src/styles/canvas.css`: a safe-area box, an eyebrow, a display line, a button, and a foot. Everything inside is written in design pixels, so the same markup is a leaderboard or a billboard. Turn on the guides to see the safe area and any band the platform covers with its own interface.
```
Eyebrow
Headline, accent.
Call to action
```
## Delivery rules `#delivery`
| Rule | What it means in practice |
| --- | --- |
| **File type** | JPG for anything with a photo, PNG for flat color and type. Export at exactly the listed pixel size unless the format says 2×. Never upload SVG or WebP to an ad platform unless its specification lists them. |
| **Weight** | Stay under the listed limit. Export a photo at about 80% JPG quality and check the file size before upload, not after a rejection. |
| **Alt text** | Where a placement takes alt text, write the message, not a description of the picture. Ad platforms take no alt text, so the message must also be in the ad's text fields. |
| **The mark on every asset** | Every paid or promotional asset carries the full brand mark from the Brand view. A monogram is never the only identification. |
| **Disclaimers** | Where the brand's field requires a disclaimer line, it appears wherever it fits at a legible size; a format too small to hold it is marked in the catalog and is not used where the line is required. |
| **Safe areas** | Keep the mark and the copy inside each format's safe area. The guides on any template page show it, with any band the platform covers. |
| **Shared copy** | A campaign reads word for word the same on every channel: the ad, the banner, the event cover, and the post take their headline, date, and call to action from one place, never retyped per template. |
---
# NachoDS
*Design system*
Repository-owned visual and interface standards.
## How this is organized `#organization`
Each view is one audience's slice of the system. Brand holds the essentials every surface shares. Web DS applies them to interfaces and email, Digital DS to ads and campaign assets, Social DS to social channels, and Print DS to paper. Use lays out every way the system is read: these pages, one URL for an AI tool, the machine-readable layer, MCP, a pinned bundle, and the website designs. Every asset format those views produce is sized from one catalog, `src/formats.json`. A planned page is declared in the navigation and not yet authored. Designs are whole pages of the eventual website, authored here on the system's own stylesheets and ported to production by engineers.
| Page | View | What it owns | Status |
| --- | --- | --- | --- |
| Foundation | Brand | What the brand stands for and the few decisions every other page follows from. | Planned |
| Logo | Brand | Each lockup on the ground it is for, clear space, minimum sizes, and misuse. | Planned |
| [Typography](/brand/typography/) | Brand | The type families, the type scale, and specimens. | Authored |
| [Color](/brand/color/) | Brand | The palette and which text color belongs on which ground. | Authored |
| Icons | Brand | The icon set, its sizes, and how it takes color. | Planned |
| Voice & Tone | Brand | How the brand sounds: rules, rewrites, and words to use or avoid. | Planned |
| [Spacing & shape](/web/spacing/) | Web DS | The spacing scale, radii, layout constants, and motion durations. | Authored |
| Photography | Web DS | Subjects, treatment, crops, and the approved image library. | Planned |
| [Components](/web/components/) | Web DS | Buttons and form fields, each with a live preview, its rules, and its markup. | Authored |
| Layout | Web DS | Grid, section rhythm, breakpoints, and how long content wraps. | Planned |
| Email principles | Web DS | How inbox-grade HTML email is built on the system: structure, type, color, and what clients strip. | Planned |
| Email templates | Web DS | Ready-to-send templates for the messages the brand sends most, each with its rules and markup. | Planned |
| [Overview](/digital/) | Digital DS | Paid ads, event banners, and promotional graphics for screens: the format catalog, delivery rules, and how a preview is built. | Authored |
| Google Display Ads | Digital DS | The standard display units in Minimal, Accent, and Bold, with the platform's weight limit and border rule. | Planned |
| Responsive & PMax | Digital DS | Image and text assets for responsive and Performance Max campaigns, within the platform's text limits. | Planned |
| Webinar Banners | Digital DS | The page hero, registration banner, and title slide for an online event. | Planned |
| Virtual Backgrounds | Digital DS | Video-call backgrounds that keep the speaker clear and the brand in the corner. | Planned |
| Email Headers & Signatures | Digital DS | The header image for campaigns and the banner under every signature. | Planned |
| Website Promos | Digital DS | The promotional hero and strip the website shows during a campaign. | Planned |
| Google Business Profile | Digital DS | Post images and the button names the profile allows. | Planned |
| [Overview](/social/) | Social DS | How the brand behaves on fixed-canvas, mobile-first channels: principles, the canvas catalog, and how the view is organized. | Authored |
| Brand on Social | Social DS | The logo, type, and color on a fixed canvas: minimum sizes, safe areas, and the one treatment per surface. | Planned |
| Voice & Tone | Social DS | How the brand voice shortens for captions, comments, and replies. | Planned |
| Video Pipeline | Social DS | How a video goes from brief to published cut, and who approves each step. | Planned |
| Video Lab | Social DS | The authoring contract and boards a drafted video is built from. | Planned |
| B-Roll Library | Social DS | The approved footage, how it is tagged, and which chains cut together. | Planned |
| LinkedIn specs | Social DS | Image, video, and document specs and character limits. | Planned |
| LinkedIn templates | Social DS | Post, carousel, and article-cover templates. | Planned |
| YouTube specs | Social DS | Channel art, video, and end-screen specs. | Planned |
| YouTube templates | Social DS | Overlay, lower-third, and bumper templates. | Planned |
| Thumbnails | Social DS | Thumbnail layouts that read at phone size, with the one treatment per series. | Planned |
| Video Assets | Social DS | Intro, outro, lower thirds, and captions styles shared by every cut. | Planned |
| Shorts | Social DS | Vertical video: safe areas under platform chrome, hook timing, and captions. | Planned |
| Eventbrite, Facebook & Webinars | Social DS | Event listing images, event covers, and webinar promo posts and stories in Minimal, Accent, and Bold. | Planned |
| Facebook | Social DS | Square, link, and story templates with caption rules. | Planned |
| Instagram | Social DS | Square, portrait, story, and carousel templates with caption rules. | Planned |
| Paid Social Ads | Social DS | Meta feed and portrait ads and LinkedIn sponsored content, with the text around each image. | Planned |
| Pillars & Cadence | Social DS | Content pillars, posting cadence, and the mix between them. | Planned |
| Compliance & A11y | Social DS | The legal and accessibility guardrails every post and ad passes before it goes out. | Planned |
| [Overview](/print/) | Print DS | How the brand meets paper, vinyl, and board: the template scale, principles, the format catalog, and the printer handoff. | Authored |
| Letterheads | Print DS | First and second sheets, the letter grid, and what prints in the office. | Planned |
| Business Cards | Print DS | Front and back in each step of the scale, with the contact line sizes. | Planned |
| Brochures | Print DS | The tri-fold panel order, copy per panel, and the fold. | Planned |
| Booklets | Print DS | Cover wraps, chapter openers, interior spreads, and the booklet style guide. | Planned |
| Worksheets | Print DS | Fill-in sheets that print on any office printer and take pen. | Planned |
| Calendar | Print DS | The year at a glance and the month page, dates computed from the year. | Planned |
| Notepads | Print DS | Tear-off pads with handwriting ruling: the brand at the head and foot, room to write between. | Planned |
| Conference Banners | Print DS | Pull-up and hanging banners sized to read across a room. | Planned |
| Posters | Print DS | Event posters in four sizes, from tabloid to one-sheet. | Planned |
| [Using the system](/use/) | Use | Every way in: the pages, one URL for any AI tool, the machine-readable layer, MCP, a pinned bundle, and the website designs. | Authored |
| [Marketing site](/designs/website/) | Designs | The public website: a home page and a contact page with its sent state, composed from the system's layout pieces and components. Starter pages; replace them with the client's. | 2 pages |
---
# The print design system
*Print DS · Foundations*
How the brand meets paper, vinyl, and board: stationery, collateral, desk and office pieces, and event display. It uses the Brand view's mark, type, and palette, and adds what the screen never needs: trim, bleed, safe areas, stock, and ink.
## The template scale `#scale`
Every template in Print, Digital, and Social ships in three steps on the same grid. Choose the step that fits the setting: a letter is Minimal, a seminar handout is Accent, and a booth in a busy hall is Bold. Do not mix steps inside one piece. A set, such as a card and its matching letterhead, may use different steps.
| Step | Surface | Accent | Mark |
| --- | --- | --- | --- |
| **Minimal** | Quiet and correspondence-grade. White or natural stock and ink-colored type; the paper does the work. | One hairline or rule. No accent fills. | The full mark in color. |
| **Accent** | Recognizable at arm's length. A band of ink or accent frames the content. | Eyebrows and one rule. The accent never fills more than about a tenth of the face. | The full mark: color on paper, reversed inside the band. |
| **Bold** | A full-bleed ink flood, or full-bleed photography where the format has room. For rooms, not envelopes. | Display type and keylines in the accent. | The full mark reversed. |
## Principles `#principles`
| Principle | What it means in practice |
| --- | --- |
| **Brand owns the identity.** | Mark files, type families, and colors come from the Brand view. Print never adds a typeface or a color; it only defines how those assets meet ink and stock. |
| **Paper is a surface.** | Prefer natural or ivory stock to a printed tint. A tint across a whole sheet muddies type and shows banding on digital presses. |
| **Readable at arm's length, then across a room.** | Body text on letters, brochures, and worksheets is at least 12 pt with generous line spacing, fill-in items are 15 pt, and running text is upright. Only supporting lines go smaller: contact lines, running heads, pad footers, and fine print, and nothing below 7.5 pt. Banner headlines read from about 12 m (40 ft). |
| **Write on paper, never on ink.** | Anything a reader fills in, ticks, circles, or signs sits on white or ivory: write-in lines, tick boxes, notes, calendar dates, date fields, signature lines. Bands and floods carry only printed type. Ballpoint and pencil vanish on ink. |
| **Compliant by default.** | Advertising pieces carry the brand's name and address and follow the claim rules of its field, the same as on [social](/social/). When in doubt, send it for review. |
> **Note.** **Ink.** Record the press build of each color token here once it is proofed: CMYK, the nearest spot color, and where each is used. Keep floods at or below 300% total ink, and never set small type in a rich build.
## Formats `#formats`
Every template page sizes its previews from the `print` group in `src/formats.json`. Bleed extends past the trim line; live type and the mark stay inside the safe area.
| Format | Trim | Bleed | Safe area | Stock | Page | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| **Letterhead · US Letter** | 8.5″ × 11″ | 0.125″ | 0.5″ | 70–80 lb uncoated text, white or natural; laser and inkjet compatible. | Letterheads Planned | Minimal prints without bleed in the office; Accent and Bold need a press with bleed. |
| **Second sheet · US Letter** | 8.5″ × 11″ | 0.125″ | 0.5″ | Same stock as the first sheet. | Letterheads Planned | |
| **Business card · US** | 3.5″ × 2″ | 0.125″ | 0.125″ | 16–32 pt uncoated or soft-touch cover. | Business Cards Planned | |
| **Tri-fold brochure · letter** | 11″ × 8.5″ | 0.125″ | 0.25″ | 100 lb gloss or silk text; 80 lb uncoated for Minimal. | Brochures Planned | Roll fold: the tuck-in panel is 1/16″ narrower than the other two. |
| **Booklet · 6 × 9 trade** | 6″ × 9″ | 0.125″ | 0.375″ | Interior 60–70 lb natural uncoated text; cover 100 lb cover with matte laminate. | Booklets Planned | Saddle-stitched at 48 pages or fewer with a page count that is a multiple of 4; perfect bound above that. |
| **Worksheet · US Letter** | 8.5″ × 11″ | 0″ | 0.5″ | 24 lb bond or 70 lb uncoated text so it takes pen and pencil. | Worksheets Planned | No bleed: a white margin on every template so it prints on any office printer. |
| **Calendar · US Letter** | 8.5″ × 11″ | 0.125″ | 0.5″ | 100 lb uncoated cover, so the sheet pins flat and takes pen. | Calendar Planned | Two single-sheet templates share this format: the year at a glance and the month page. |
| **Notepad · half letter** | 5.5″ × 8.5″ | 0.125″ | 0.375″ | 60–70 lb uncoated text, 50 sheets, padded at the head onto chipboard. | Notepads Planned | Top-glued: the padding compound takes about 1/8″ at the head, so nothing sits above the safe line. |
| **Desk pad · 4 × 6** | 4″ × 6″ | 0.125″ | 0.25″ | Same text stock, 50 sheets, padded at the head. | Notepads Planned | |
| **Retractable pull-up banner** | 33″ × 80″ | 0.5″ | 1″ | 13 oz anti-curl vinyl or polyester fabric. | Conference Banners Planned | The bottom 8″ disappears into the stand cassette; keep everything critical above it. |
| **Hanging or table banner** | 96″ × 36″ | 0.5″ | 1.5″ | 13 oz matte vinyl with grommets, or dye-sublimated fabric. | Conference Banners Planned | Grommets sit 1″ in from each corner and every 24″; nothing within 1.5″ of the edge. |
| **Poster · tabloid** | 11″ × 17″ | 0.125″ | 0.5″ | 100 lb gloss text; in-office or digital press. | Posters Planned | |
| **Poster · medium** | 18″ × 24″ | 0.125″ | 0.75″ | 100 lb silk cover or 9 mil satin photo paper. | Posters Planned | |
| **Poster · large** | 24″ × 36″ | 0.125″ | 1″ | 9 mil satin photo paper; foam-core mount for easels. | Posters Planned | |
| **Poster · one-sheet** | 27″ × 40″ | 0.125″ | 1″ | 9 mil satin photo paper, or backlit film for light boxes. | Posters Planned | |
## Previews `#previews`
A sheet is a print canvas (`canvas--print`) sized from the catalog, so one preview unit is one inch and type is set in points. It is composed from the same pieces as a screen canvas, in `src/styles/canvas.css`. Turn on the guides to see the safe area.
## Handing off to a printer `#handoff`
| Item | Requirement |
| --- | --- |
| **File** | PDF/X-4, CMYK (or CMYK plus a spot for foil), fonts embedded, crop marks offset beyond the bleed. |
| **Images** | 300 ppi at final size for sheet goods; 100 to 150 ppi at final size for banners and posters 24″ and up. |
| **Mark** | Vector files only, from the Brand view. Never place a screenshot or a raster export. |
| **Proof** | A hard proof on the chosen stock for every first run and every new stock. |
---
# The social design system
*Social DS · Foundations*
How the brand shows up on social channels. It inherits the identity from the Brand view and adapts it to fixed-canvas, mobile-first surfaces, then layers on the platform specs, the post and event templates, and the compliance rules every post passes before it goes out.
## Principles `#principles`
This view does not redefine the brand; it translates it. Colors, fonts, the mark, and voice are owned by Brand. This view governs how those assets behave on a square post or a vertical story.
| Principle | What it means in practice |
| --- | --- |
| **One brand, every channel.** | A post is recognizable before the mark is read: the same palette, the same display type, the same accent. Never introduce a social-only color or typeface. |
| **Platform-native, not platform-generic.** | Respect each channel's dimensions, safe areas, and reading behavior. A document carousel and a video thumbnail are different crafts; design for where each is seen. |
| **Mobile-first legibility.** | Most impressions are on a phone. Type, contrast, and the focal point must hold at thumbnail scale before a post is approved at full size. |
| **Compliant by default.** | Claims, testimonials, and results follow the rules of the brand's field. When in doubt, a post goes to review before it goes out. |
## How it's organized `#organization`
| Group | Covers |
| --- | --- |
| **Foundations** | Brand assets on a fixed canvas, and the social voice and tone. |
| **Production** | How a video goes from brief to published cut, the lab it is drafted in, and the footage library. |
| **LinkedIn, YouTube, Shorts** | Each platform's specs and templates, and vertical video under platform chrome. |
| **Events** | Event listing images, event covers, and webinar promo posts and stories in Minimal, Accent, and Bold. |
| **Post Templates** | Feed, story, and carousel templates per platform, with caption rules. |
| **Advertising** | Paid social ads and the text around each image. Display and search placements live in [Digital DS](/digital/). |
| **Content & Compliance** | Content pillars, posting cadence, and the legal and accessibility guardrails. |
> **Note.** **Canonical tokens live in Brand.** Anything in this view that references a color, font, or the mark defers to the Brand view. If they ever disagree, Brand wins and this page is wrong.
## Canvases `#canvases`
Every event image, post, and ad is sized from the `social` group in `src/formats.json`, and a template is built from the same pieces as Digital DS (`src/styles/canvas.css`). A story keeps its message out of the bands the platform covers with its own interface; turn on the guides to see them.
| Format | Size | Safe area | File | Max weight | Page | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| **Eventbrite event image** | 2160 × 1080 px | 108 px | JPG or PNG, under 10 MB | | Eventbrite, Facebook & Webinars Planned | Listings crop toward the centre; keep the headline in the middle 1600 px. |
| **Facebook event cover** | 1920 × 1005 px | 96 px | JPG or PNG | | Eventbrite, Facebook & Webinars Planned | |
| **LinkedIn event cover** | 1776 × 444 px | 64 px | JPG or PNG | | Eventbrite, Facebook & Webinars Planned | |
| **Webinar promo post** | 1080 × 1080 px | 64 px | JPG or PNG | | Eventbrite, Facebook & Webinars Planned | |
| **Webinar story** | 1080 × 1920 px | 64 px | JPG or PNG | | Eventbrite, Facebook & Webinars Planned | |
| **Facebook square post** | 1080 × 1080 px | 64 px | JPG or PNG | | Facebook Planned | |
| **Facebook link or landscape post** | 1200 × 630 px | 60 px | JPG or PNG | | Facebook Planned | |
| **Facebook story** | 1080 × 1920 px | 64 px | JPG or PNG | | Facebook Planned | |
| **Instagram square** | 1080 × 1080 px | 64 px | JPG | | Instagram Planned | |
| **Instagram portrait** | 1080 × 1350 px | 64 px | JPG | | Instagram Planned | The profile grid crops portrait posts to 3:4; keep copy inside the centred 1012 × 1350. |
| **Instagram story or reel cover** | 1080 × 1920 px | 64 px | JPG | | Instagram Planned | |
| **Meta feed ad** | 1080 × 1080 px | 64 px | JPG or PNG | | Paid Social Ads Planned | |
| **Meta feed ad · portrait** | 1080 × 1350 px | 64 px | JPG or PNG | | Paid Social Ads Planned | |
| **LinkedIn sponsored** | 1200 × 627 px | 60 px | JPG or PNG | | Paid Social Ads Planned | |
---
# Using the system
*Use*
NachoDS is published once and read many ways: as these pages in a browser, as one text file an AI tool reads, as a machine-readable layer a script joins, over MCP for an agent, as a pinned bundle a website loads, and as whole-page designs a developer ports. This page lays out each way in, who it is for, and what to take from it. Every way in reads the same published release, so every reader works from the same brand.
## Who uses it, and how `#audiences`
Each way in serves one kind of reader. Start from the row that describes you; the rest of this page explains each one.
| Reader | Way in | Start with |
| --- | --- | --- |
| **A person**: a designer, writer, marketer, or printer | These pages, in a browser | The Brand view, then the view for the surface at hand |
| **An AI assistant** that reads a URL | One text file with the brand essentials and the page index | [`/llms.txt`](/llms.txt) |
| **An agent with MCP** | The `timds-design-system-read` server | `get_consumer_guide`, then `describe_system` |
| **A script or pipeline** | The machine-readable layer beside the pages | [`/index.json`](/index.json), [`/tokens.json`](/tokens.json), [`/brand.json`](/brand.json) |
| **A website or app** | A pinned release and its consumer bundle | `timds.consumer.json` at the product's root |
| **A developer building a page** | The website designs: whole pages on the system's own stylesheets | The `/designs/` directory in the app bar |
| **A designer, or an agent changing the system** | The system's repository and its editing tools | `AGENTS.md` in the repository |
## Read it in a browser `#browser`
These pages are the published artifact itself, built from the system's source on every release. Each view is one audience's slice of the system, and every page follows the same shape: an eyebrow, a title, a summary, then one block per topic.
| On the page | What it is |
| --- | --- |
| **A table** | The rules. Each row is one record every other way in can cite, so a specification or a do-and-don't lives in a table, never in prose. |
| **A note** | Guidance that is not a row: a reason, a caution, an exception. |
| **A code block** | Markup to copy as written. |
| **A preview** | A live sample of the thing described. Its sample text is illustration, never a rule. |
| **Planned** | A page declared in the navigation and not yet written. Nothing is published for it, so no reader receives placeholder guidance. |
| **The version in the app bar** | The release these pages belong to. Every merged change becomes a new patch release. |
| **Markdown** | The check writes a mirror of every page at `index.md` beside it, the same content as plain text. This page's is [`/use/index.md`](/use/index.md). |
## One URL for any AI tool `#llms`
A person who wants an assistant to work on-brand pastes one address. The file opens with how to use it, so the tool needs no other instruction.
| File | Holds | Use it when |
| --- | --- | --- |
| [`/llms.txt`](/llms.txt) | How to use the file, then the brand essentials: every role color as hex, every font with its family and the files or service that provide it, every logo by variant with its URL, every asset format with its size, and then the page directory. | Pasting the system into a chat, or into any tool that reads a URL. |
| [`/llms-full.txt`](/llms-full.txt) | Every page's Markdown in one file. | A tool that reads a single URL and needs the whole system, not a directory to follow. |
> **Note.** Both files are generated from the built pages on every check, never written by hand, and the published copies carry absolute URLs, so either one can be handed around on its own.
## The machine-readable layer `#machine`
The check (`npm run timds -- check`) reads the built HTML and CSS and writes these documents beside the pages, and every release publishes them; a plain dev build serves the pages without them. Nothing in them is maintained by hand, so they cannot drift from what the pages say. A script, a render pipeline, or a host reads them directly; the MCP server below serves the same documents.
| Document | Holds |
| --- | --- |
| [`index.json`](/index.json) | Every page as structured blocks: rules from its tables, one record per row, notes, code, and assets joined to their media records. |
| [`tokens.json`](/tokens.json) | Every CSS custom property the pages load, resolved, with the scope and kind of each, and the brand roles they fill. |
| [`brand.json`](/brand.json) | The brand kit: the role colors and fonts, each font with the files or service that provide it, every logo and image presented as brand material, and the guidance groups. |
| `formats.json` | Every print sheet and screen canvas with its size, bleed, and safe area, when the system keeps a format catalog. |
| `designs.json` | Every website design page and state as HTML, with the files it loads. |
| `bundle.json` | Every file in the consumer bundle with its size and digest, and the immutable copy of this version a website pins. |
| `index.md` | Beside every page, its Markdown mirror. |
| Brand role | Answers |
| --- | --- |
| `color.background`, `color.panel` | The page ground and the raised surface on it. |
| `color.accent` | The one color that signals an action or a highlight. |
| `color.text`, `color.muted` | Body text and secondary text. |
| `font.display`, `font.body`, `font.ui` | Headings, running text, and interface labels. |
> **Note.** Every record carries a stable id, such as `brand/voice#principles`: the page, then the block, then the row. Cite the id, and a reviewer can resolve it. A block's id is the citation, so it is never renamed casually.
> **Note.** Ask for a role, not a token name. A role resolves to the token that fills it and that token's value, so a consumer never has to know how this system names things. A role nothing fills is a gap the system reports, never a value to guess.
## Connect an agent over MCP `#mcp`
The `timds-design-system-read` server serves the layer above to any MCP-capable agent. It is read-only apart from filing a gap, never sees authored source, and serves the current published release by default; `version` selects an earlier one. Every result names the version it was read from.
| Where it runs | How to connect |
| --- | --- |
| **Hosted** | The TimDS portal serves it over HTTP, authorized with an access token. In a product, `timds consumer init` writes the entry into `.mcp.json`. |
| **Against a checkout** | `npm run timds -- mcp read` in the system's repository, after a check has built the layer. |
| **Against the published copy** | `npm run timds -- mcp read --published URL`, with the system's published root. |
| Tool | Gives |
| --- | --- |
| `get_consumer_guide` | How to use a system to produce on-brand work. Read it first. |
| `list_design_systems`, `describe_system` | What is in scope; the served, published, and pinned versions; the page directory; the consumer bundle and its immutable copy. |
| `resolve_role` | A brand role to the token that fills it and its value. An unfilled role is a reported gap, never a guess. |
| `get_tokens` | Resolved custom properties by name, kind, or scope, such as a dark theme. |
| `get_brand` | The roles, each font with its sources, the logos, the imagery, and the guidance groups. |
| `list_formats` | The asset format catalog: every sheet and canvas with its size, bleed, and safe margin. |
| `list_pages`, `read_page` | The page directory, and one page or one block as Markdown or as structured blocks. |
| `list_designs`, `read_design` | The website designs, and one page state's HTML with the files it loads. |
| `search_guidance` | The blocks that answer a question, guidance groups first, every result cited by page and block. |
| `list_media` | The published media catalog by tag or kind, each with a stable public URL. |
| `report_gap` | Files one gap into the system's request intake, when the host provides one. |
> **Note.** The resources `timds://brand.json`, `timds://tokens.json`, `timds://index.json`, `timds://llms.txt`, `timds://formats.json`, `timds://bundle.json`, and `timds://guidance/{group}` serve the same documents to a client that reads resources rather than calling tools.
## Pin it in a website or app `#products`
A product never copies the system. It pins a release in `timds.consumer.json` at its root and installs that release's consumer bundle: the stylesheets, scripts, and small assets the system names in `bundle.include`, fetched into the product's ignored `design-system/` directory under the same paths they have here, every digest verified. A clone and an install is all a product, or an agent working in it, needs.
| Step | Command | What it does |
| --- | --- | --- |
| **Adopt** | `npm run timds -- consumer init --system ID` | Writes the manifest with a published pin, wires the sync into `postinstall`, and installs the consumer skill, the preview workflows, and the hosted MCP entry. |
| **Install** | `npm ci` | Fetches the pinned bundle and verifies it. |
| **Move the pin** | `npm run timds -- consumer update VERSION` | Moves to a version, or without one to the current release. A pin of `current` follows every release at the next install. |
| **Check** | `npm run timds -- consumer check` | Validates the manifest and the pin, and that a branch stays inside the product's declared design surface. |
| **Review** | `npm run timds -- consumer preview --app NAME` | Captures each route at desktop and phone widths in both color schemes, with the paired design beside it. |
> **Note.** A pin names an immutable copy of the release, so a later release never changes what a pinned product loads. In product CSS use a token by name, never by its literal value, so the product follows the pin. The `timds-consume-design-system` skill the adoption installs tells an agent how to make a design change in the product; when the system lacks what a change needs, the fix is a pull request to the system, never a product-side workaround.
## Port the website designs `#designs`
The system is designer-owned down to the pages. A designer authors whole pages in HTML on the system's own stylesheets, the build writes them to `/designs/`, and the app bar links there. A named state is a file beside its page, so every state a developer must build is a page they can open.
| Rule | In practice |
| --- | --- |
| **The design is the reference** | A port matches it on the product's own stack with the system's stylesheets. The design file is never copied into the product as a page, and never restyled. |
| **Every state is a file** | Port each one. A state the product cannot express is a developer change to raise, not an omission. |
| **Pair the route** | In the product's manifest, a route is paired with its design so a review shows the two side by side. |
| **Read it as data** | `designs.json`, and `list_designs` and `read_design` over MCP, carry every page state's HTML with the files it loads. |
## Change the system `#change`
Nothing above is edited in place. The system is a repository, every change is a pull request there, and merging releases a patch version that every reader above picks up on its next read.
| Who | Where | How |
| --- | --- | --- |
| **A designer, or an agent acting for one** | The system's repository | `AGENTS.md` is the working contract and the `timds-edit-design-system` skill holds the procedure. `npm run timds -- check` validates the change and `submit` opens the draft pull request. |
| **An agent without a checkout** | The `timds-design-system` editing server, `npm run timds -- mcp` | Guarded reads and writes of the authored surface, a check as structured findings, and the derived layer. Protected tooling is refused, not merely discouraged. |
| **A product that found a gap** | `report_gap` over MCP, or a pull request to the system | A missing token, role, component, or rule is fixed in the system, and the product waits for the next release. |
| **Video, when the system declares it** | The same repository | The `timds-create-video` skill and the `video` commands, on the client's own video contract. |
## Versions `#versions`
Three versions matter to a reader, and every document and tool result says which one it carries.
| Version | Meaning |
| --- | --- |
| **Served** | The release a read returned. Every derived document and every MCP result names it. |
| **Published** | The current release, and the default for every way in on this page. |
| **Pinned** | The release a product is built against. It trails the published release until a developer moves the pin. |
> **Note.** Each merged change becomes a patch release, published to the portal and to the stable address every way in on this page reads from. The number in the app bar is the release these pages belong to; this copy is 0.1.0.
---
# Components
*Web DS · Library*
Each component is a live preview, the rules for using it, and the markup to copy. Their styles live in `/styles/system.css`.
## Buttons `#buttons`
A button starts an action. A link that only navigates stays a link.
| Variant | Class | Use |
| --- | --- | --- |
| Primary | `.button` | The one action a view exists for; at most one per view |
| Secondary | `.button.button--secondary` | Every other action beside or below the primary |
```
```
## Form fields `#fields`
A field is a label, a control, and optional help text, in that order.
| Part | Element | Rule |
| --- | --- | --- |
| Label | `label` | Always visible and tied to the control with `for`; a placeholder is not a label |
| Control | `input` | At least 3rem tall so it is easy to hit on touch screens |
| Help text | `small` | One sentence directly under the control |
```
Keep help text close to the control.
```
## Site layout `#layout`
The pieces a whole page is composed from. The website design under [Designs](/designs/) uses only these and the components above, so a page needs nothing a product does not already get from `/styles/system.css`.
| Piece | Class | Use |
| --- | --- | --- |
| Wrap | `.wrap` | Centers a band of the page at the content width with side gutters; the header, main content, and footer each sit in one |
| Site header | `.site-header`, `.site-header__brand`, `.site-nav` | The brand link and the site navigation at the top of every page |
| Hero | `.hero` | The opening band: one heading, one paragraph, then the actions |
| Section | `.section` | Each further band of a page, with a heading and short copy; give it an `id` so the page can link to it |
| Form | `.form` | Stacks fields and their submit button |
| Notice | `.notice` | A confirmation or status message in its own panel |
| Site footer | `.site-footer` | The closing line of every page |
---
# Spacing & shape
*Web DS · Tokens*
The values that fix rhythm and geometry: one spacing scale, three radii, the constants of the page shell, and how long a state change takes.
## Spacing scale `#scale`
Padding, margin, and gap all come from this scale. The step name is its multiple of 0.25rem.
| Token | Custom property | Value |
| --- | --- | --- |
| `space.1` | `--space-1` | `0.25rem` |
| `space.2` | `--space-2` | `0.5rem` |
| `space.3` | `--space-3` | `0.75rem` |
| `space.4` | `--space-4` | `1rem` |
| `space.6` | `--space-6` | `1.5rem` |
| `space.8` | `--space-8` | `2rem` |
| `space.12` | `--space-12` | `3rem` |
## Radius `#radius`
| Token | Custom property | Value | Use |
| --- | --- | --- | --- |
| `radius.sm` | `--radius-sm` | `0.5rem` | Buttons, inputs, and tags. |
| `radius.md` | `--radius-md` | `0.875rem` | Panels and preview stages. |
| `radius.round` | `--radius-round` | `999px` | Circular indicators only. |
## Layout constants `#layout-constants`
Four values fix the page shell. Everything else is spacing.
| Token | Custom property | Value | Use |
| --- | --- | --- | --- |
| `size.content` | `--size-content` | `76rem` | Maximum width of the page shell. |
| `size.sidebar` | `--size-sidebar` | `15rem` | Width of the page navigation. |
| `size.header` | `--size-header` | `4rem` | Height of the app bar. |
| `size.line` | `--size-line` | `1px` | Every rule and border. |
## Motion `#motion`
Motion confirms a state change. Under `prefers-reduced-motion: reduce` every transition collapses, and nothing depends on animation to become readable.
| Token | Custom property | Value | Use |
| --- | --- | --- | --- |
| `motion.fast` | `--motion-fast` | `160ms` | Hover and focus response. |