{
"name": "@gabrielpule/mcss-lite",
"version": "0.4.1",
"description": "Contract-first CSS design system: every class, state and token is declared in machine-readable contracts, so people and AI agents build UI with the right parts.",
"generatedFrom": [
"tokens/*.tokens.json",
"components/*.json"
],
"cascade": [
"global",
"layout",
"component",
"utility"
],
"prefixes": {
"l-": "layout primitive",
"c-": "component",
"u-": "utility"
},
"naming": "BEM: block, block__element, block--modifier. State: data-state=\"value\" on the block.",
"themes": {
"attribute": "data-theme",
"default": "light",
"values": {
"light": "Light theme. Also the default when no data-theme attribute is set.",
"dark": "Dark theme.",
"auto": "Follows the operating system via prefers-color-scheme."
}
},
"rules": [
{
"id": "golden-rule",
"title": "Components never set their own outer margin",
"text": "Never add margin to a c-* root element. Put components inside a layout primitive (l-stack, l-cluster, l-grid, l-sidebar, l-switcher) and let it provide the spacing."
},
{
"id": "lookup-order",
"title": "Layout, then component, then utility, then token",
"text": "Solve a need with an l-* layout primitive first, then a c-* component and its modifiers, then a u-* utility. Only write custom CSS as a last resort, and then use var(--token) values only."
},
{
"id": "no-invention",
"title": "Never invent class or token names",
"text": "Use only the classes, modifiers, elements, data-state values and tokens listed in this file. If something is missing, write custom CSS with existing tokens instead of guessing a name such as c-button--warning."
},
{
"id": "states",
"title": "States use data-state plus the native or ARIA pair",
"text": "Express component state with data-state=\"…\" (for example data-state=\"error\"), and always add the paired native attribute or ARIA listed for that state (disabled, aria-invalid, aria-busy). Checkboxes, radios and toggles are the exception: their states are native (checked, disabled, aria-invalid) and never use data-state."
},
{
"id": "theming",
"title": "Theme with semantic tokens, never raw values",
"text": "Never hard-code colors (#hex, rgb()) or pixel spacing. Use semantic tokens (--color-text-default, --color-action-primary…) or component tokens (--button-primary-background…). Primitive color tokens (--color-gray-*, --color-blue-*) do not adapt to dark mode."
}
],
"contentRules": [
{
"id": "sentence-case",
"title": "Write in sentence case",
"text": "Capitalize only the first word and proper nouns in labels, titles, buttons and badges. Title Case is harder to scan and reads as shouting in long labels.",
"do": "Create account",
"dont": "Create Account",
"enforcedBy": "content-case"
},
{
"id": "button-verbs",
"title": "Buttons say what happens",
"text": "Start with a verb and name the thing it acts on. A person should know the result before they click.",
"do": "Save changes",
"dont": "OK"
},
{
"id": "no-vague-labels",
"title": "No vague labels",
"text": "\"Submit\", \"Click here\", \"Yes\" and \"More\" say nothing out of context. Screen reader users often hear a list of every link or button on the page, with no surrounding text.",
"do": "Download the invoice",
"dont": "Click here",
"enforcedBy": "content-vague"
},
{
"id": "error-messages",
"title": "Errors say what went wrong and how to fix it",
"text": "Name the problem in plain words and tell the person what to do. Don't blame, don't use codes, don't say \"invalid\".",
"do": "Enter a date after 1 January 2020",
"dont": "Invalid input"
},
{
"id": "error-timing",
"title": "Show errors at the right moment",
"text": "Check a field when the person leaves it or submits the form, not while they type its first value. Once a field shows an error, clear it as soon as the value is fixed. After a failed submit, list every error at the top of the form, each linked to its field.",
"do": "There is a problem: Enter your email address",
"dont": "Email is invalid (shown after the first keystroke)"
},
{
"id": "optional-fields",
"title": "Mark optional fields, not required ones",
"text": "Ask only for what you need, then add \"(optional)\" to the few fields people may skip. Rows of asterisks add noise and need a legend.",
"do": "Phone number (optional)",
"dont": "Phone number *"
},
{
"id": "positive-choices",
"title": "Write choices as positive statements",
"text": "A checkbox label is a statement the person agrees with by ticking it. Negatives make them untick to say yes, and people get it wrong.",
"do": "Email me about new releases",
"dont": "Don't email me about new releases"
},
{
"id": "setting-names",
"title": "Name the setting, not the action",
"text": "A toggle's label names what it controls and never changes; the switch itself says on or off. Labels like \"Turn on\" leave people guessing which state is current.",
"do": "Dark mode",
"dont": "Enable dark mode"
},
{
"id": "punctuation",
"title": "Keep punctuation light",
"text": "No full stops on buttons, titles, labels or badges. Use full stops in help text and messages that are sentences. Avoid exclamation marks.",
"do": "Delete project",
"dont": "Delete project!"
},
{
"id": "numbers-dates",
"title": "Write numbers and dates the same way everywhere",
"text": "Use numerals for numbers, the full month name in dates and a consistent time format. Avoid ambiguous dates like 03/04.",
"do": "1 March 2026, 12 of 20 seats",
"dont": "03/01/26, twelve of twenty seats"
},
{
"id": "inclusive",
"title": "Write for everyone",
"text": "Use plain words, active voice and \"you\". Avoid idioms, jargon and gendered defaults. Describe what something does, not how it looks (\"select\", not \"click the blue button\").",
"do": "Choose a plan to continue",
"dont": "Just hit the big blue button, guys"
}
],
"icons": {
"sprite": "dist/mcss-lite.icons.svg",
"idPrefix": "mcss-icon-",
"names": [
"arrow-right",
"check",
"chevron-down",
"chevron-left",
"chevron-right",
"chevron-up",
"close",
"copy",
"download",
"edit",
"error",
"external-link",
"info",
"menu",
"minus",
"plus",
"search",
"success",
"trash",
"warning"
]
},
"pages": [
"demo/index.html",
"demo/status.html",
"demo/content.html",
"demo/components/center.html",
"demo/components/cluster.html",
"demo/components/container.html",
"demo/components/grid.html",
"demo/components/section.html",
"demo/components/sidebar.html",
"demo/components/stack.html",
"demo/components/switcher.html",
"demo/components/alert.html",
"demo/components/badge.html",
"demo/components/button.html",
"demo/components/card.html",
"demo/components/checkbox.html",
"demo/components/form-field.html",
"demo/components/icon.html",
"demo/components/input.html",
"demo/components/label.html",
"demo/components/modal.html",
"demo/components/radio.html",
"demo/components/toggle.html",
"demo/components/utilities.html"
],
"blocks": [
{
"name": "Center",
"block": "l-center",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "Centers a block horizontally at reading width without side gutters.",
"guidelines": {
"whenToUse": [
"Long-form text or a single form that should sit at a comfortable reading width."
],
"whenNotToUse": [
"The outermost page wrapper that also needs side gutters: use `l-container`.",
"Inside another centered block: one reading width per column is enough."
],
"doDont": [
{
"do": {
"text": "Center one column of reading content.",
"html": "
\n
Articles read best at 60 to 75 characters per line.
\n"
}
],
"sources": [
{
"title": "Every Layout: The Center",
"url": "https://every-layout.dev/layouts/center/"
}
]
},
{
"name": "Cluster",
"block": "l-cluster",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "Horizontal group that wraps, with a gap and vertically centered items: button groups, badge lists, tags.",
"guidelines": {
"whenToUse": [
"Button groups, badge lists, tags and metadata rows that should wrap on narrow screens."
],
"whenNotToUse": [
"Two columns of page content: use `l-sidebar` or `l-grid`.",
"Items that must stay equal width: use `l-switcher`."
],
"use": [
"Group inline items such as buttons and badges."
],
"avoid": [
"Using l-cluster for two-column page layouts; use l-sidebar or l-grid."
],
"doDont": [
{
"do": {
"text": "Let items wrap; the gap holds on every row.",
"html": "
\n Design\n Research\n Accessibility\n
"
},
"dont": {
"text": "Don't space items with margins.",
"html": "
\n"
}
]
},
{
"name": "Grid",
"block": "l-grid",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "Two-dimensional grid with a fixed gap. Column modifiers collapse to one column below 768px.",
"modifiers": [
{
"group": "columns",
"exclusive": true,
"values": [
{
"name": "2-col",
"description": "Two equal columns."
},
{
"name": "3-col",
"description": "Three equal columns."
},
{
"name": "4-col",
"description": "Four equal columns."
},
{
"name": "responsive",
"description": "As many 280px-minimum columns as fit; no breakpoint needed."
}
]
}
],
"guidelines": {
"whenToUse": [
"Card collections of unknown length: l-grid--responsive fits as many columns as there is room for.",
"Dashboards with a fixed number of equal columns: l-grid--2-col, --3-col or --4-col."
],
"whenNotToUse": [
"A main area with a narrower side column: use `l-sidebar`.",
"A row of equal items that should all stack at once: use `l-switcher`."
],
"use": [
"Prefer l-grid--responsive for card collections of unknown length."
],
"avoid": [
"Adding margins to grid children; the gap already spaces them."
],
"doDont": [
{
"do": {
"text": "Keep the source order the same as the visual order.",
"html": "
",
"rule": "exclusive-modifiers"
}
}
],
"content": [
"If you reorder items visually with CSS, keyboard and screen reader users still get the source order, so change the markup instead."
]
},
"tokens": [
"--space-6"
],
"related": [
"c-card",
"l-switcher"
],
"examples": [
{
"file": "components/layouts.html",
"html": "\n
\n
\n
Projects
\n\n
\n \n
\n
\n \n
Atlas
\n
12 pages
\n \n \n
Borealis
\n
4 pages
\n \n \n
Cirrus
\n
7 pages
\n \n
\n
\n
\n\n
\n
Side by side on wide screens
\n
Stacked on narrow screens
\n
\n\n
\n
Centered at reading width.
\n
\n
\n
\n"
}
],
"sources": [
{
"title": "Defensive CSS: auto-fit vs auto-fill",
"url": "https://defensivecss.dev/tip/auto-fit-fill/"
},
{
"title": "MDN: Grid layout and accessibility",
"url": "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_and_accessibility"
}
]
},
{
"name": "Section",
"block": "l-section",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "Vertical padding for a full-width page section.",
"modifiers": [
{
"group": "size",
"exclusive": true,
"values": [
{
"name": "sm",
"description": "Smaller vertical padding (2.5rem instead of 4rem)."
}
]
}
],
"guidelines": {
"whenToUse": [
"Full-width bands of a page that need vertical breathing room, such as a hero or a feature row."
],
"whenNotToUse": [
"Spacing between components inside a section: use `l-stack`.",
"A bordered group of content: use `c-card`."
],
"doDont": [
{
"do": {
"text": "Put a container inside the section for the side gutters.",
"html": "\n
\n
Features
\n
\n"
},
"dont": {
"text": "Don't invent size modifiers; use l-section--sm for a tighter band.",
"html": "\n
\n"
}
]
},
{
"name": "Sidebar",
"block": "l-sidebar",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "A sidebar next to main content that stacks when the content would get narrower than 50%.",
"elements": [
{
"name": "sidebar",
"description": "The narrow side (16rem basis).",
"required": true
},
{
"name": "content",
"description": "The main content; takes the remaining space.",
"required": true
}
],
"guidelines": {
"whenToUse": [
"Filters next to results, a form label next to its field, an avatar next to text.",
"Any side column that should drop below the content when space runs out."
],
"whenNotToUse": [
"Equal columns: use `l-grid` or `l-switcher`.",
"Page-level navigation that must stay fixed while scrolling: that is app chrome, outside this layout."
],
"doDont": [
{
"do": {
"text": "Put the side column first in the source only if it should also be read first.",
"html": "
\n \n
42 results
\n
"
},
"dont": {
"text": "Don't use the sidebar elements on their own.",
"html": "",
"rule": "element-outside-block"
}
}
]
},
"children": [
"Exactly two children: l-sidebar__sidebar and l-sidebar__content, in either order."
],
"tokens": [
"--space-6"
],
"related": [
"l-grid",
"l-switcher"
],
"examples": [
{
"file": "components/layouts.html",
"html": "\n
\n
\n
Projects
\n\n
\n \n
\n
\n \n
Atlas
\n
12 pages
\n \n \n
Borealis
\n
4 pages
\n \n \n
Cirrus
\n
7 pages
\n \n
\n
\n
\n\n
\n
Side by side on wide screens
\n
Stacked on narrow screens
\n
\n\n
\n
Centered at reading width.
\n
\n
\n
\n"
}
],
"sources": [
{
"title": "Every Layout: The Sidebar",
"url": "https://every-layout.dev/layouts/sidebar/"
},
{
"title": "Josh Comeau: Container queries",
"url": "https://www.joshwcomeau.com/css/container-queries-introduction/"
}
]
},
{
"name": "Stack",
"block": "l-stack",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "Vertical flow: adds space between consecutive children, which keep their own width. Bare inline children (links, spans) stack too. The default way to space components vertically.",
"modifiers": [
{
"group": "gap",
"exclusive": true,
"values": [
{
"name": "sm",
"description": "Tight spacing (0.5rem), e.g. form-field internals or list items."
},
{
"name": "lg",
"description": "Loose spacing (2rem), e.g. between page blocks."
}
]
}
],
"guidelines": {
"whenToUse": [
"Anything that flows top to bottom: form fields, paragraphs, a card body, a page column.",
"Changing rhythm: nest a smaller stack (l-stack--sm) inside a larger one."
],
"whenNotToUse": [
"Items in a row that wrap: use `l-cluster`.",
"Two-dimensional layouts: use `l-grid`."
],
"use": [
"Nest stacks with different gaps to build rhythm."
],
"avoid": [
"Adding margins to children to fix spacing; change the stack modifier instead."
],
"doDont": [
{
"do": {
"text": "Let the stack own the space between its children.",
"html": "
\n
Billing
\n
Your plan renews on 1 March.
\n
\n \n
\n
"
},
"dont": {
"text": "Don't fix spacing with margins on the children.",
"html": "
\n
Plan
\n
",
"rule": "golden-rule"
}
},
{
"do": {
"text": "Pick the gap with a modifier.",
"html": "
\n
Line one
\n
Line two
\n
"
},
"dont": {
"text": "Don't combine two gap modifiers.",
"html": "
\n"
}
],
"sources": [
{
"title": "Every Layout: The Stack",
"url": "https://every-layout.dev/layouts/stack/"
},
{
"title": "LogRocket: CSS gap vs margin",
"url": "https://blog.logrocket.com/css-gap-vs-margin/"
}
]
},
{
"name": "Switcher",
"block": "l-switcher",
"layer": "layout",
"status": "stable",
"since": "0.1.0",
"description": "Children sit side by side until the container is narrower than a threshold, then all stack at once.",
"customProperties": [
{
"name": "--switcher-threshold",
"default": "30rem",
"description": "Container width below which children stack. Set inline, e.g. style=\"--switcher-threshold: 40rem\"."
}
],
"guidelines": {
"whenToUse": [
"Two to four items of equal importance, such as pricing tiers or steps, that should switch from a row to a column all at once."
],
"whenNotToUse": [
"Items of unequal importance: use `l-sidebar`.",
"Five or more items, or a list of unknown length: use `l-grid` with l-grid--responsive."
],
"doDont": [
{
"do": {
"text": "Set the threshold with the custom property.",
"html": "
\n"
}
],
"sources": [
{
"title": "Every Layout: The Switcher",
"url": "https://every-layout.dev/layouts/switcher/"
}
]
},
{
"name": "Alert",
"block": "c-alert",
"layer": "component",
"status": "beta",
"since": "0.4.0",
"description": "A printed notice on the page: tells people about something that affects what they are doing, with its severity in an icon, a word and a heavier bottom edge.",
"tags": [
"div",
"section",
"aside"
],
"modifiers": [
{
"group": "tone",
"exclusive": true,
"values": [
{
"name": "info",
"description": "Neutral information. Circle icon, \"Information:\" prefix."
},
{
"name": "success",
"description": "Something finished well. Square check icon, \"Success:\" prefix."
},
{
"name": "warning",
"description": "Something may go wrong unless the person acts. Triangle icon, \"Warning:\" prefix."
},
{
"name": "error",
"description": "Something went wrong; also the error summary at the top of a form. Octagon icon, \"Error:\" prefix."
}
]
}
],
"elements": [
{
"name": "icon",
"description": "The keylined tile that holds the severity icon (a c-icon, aria-hidden).",
"tags": [
"span",
"div"
]
},
{
"name": "body",
"description": "Title, text and actions.",
"tags": [
"div"
],
"required": true
},
{
"name": "title",
"description": "One short line. Starts with the visually hidden severity prefix.",
"tags": [
"p",
"h2",
"h3",
"h4",
"strong"
]
},
{
"name": "actions",
"description": "Buttons or links that resolve the alert, in an l-cluster.",
"tags": [
"div"
]
},
{
"name": "close",
"description": "Dismiss button, 44px, with aria-label. The app sets hidden on the alert when it is pressed.",
"tags": [
"button"
]
}
],
"children": [
"Order: c-alert__icon, c-alert__body (c-alert__title, text, c-alert__actions), then an optional c-alert__close.",
"Start c-alert__title with Error: (or Warning, Success, Information), so severity never relies on the icon or the edge."
],
"guidelines": {
"whenToUse": [
"Something on this page needs attention: a failed save, an expiring plan, a limit reached.",
"The error summary at the top of a form after a failed submit, with a link to each field.",
"Confirming that an action finished, when the page stays where it is."
],
"whenNotToUse": [
"An error about one field: use its `c-form-field` error message.",
"A decision the person must make before going on: use `c-modal`.",
"A status label on an item: use `c-badge`."
],
"use": [
"Say what happened and what to do next, in that order.",
"Keep alerts in the page flow near what they are about, spaced by a layout primitive.",
"Give role=\"alert\" only to urgent messages that appear after something the person just did. Leave it off alerts that are there when the page loads."
],
"avoid": [
"More than one alert of the same tone at once; combine them.",
"A dismiss button on a warning about data loss or cost; it must stay until resolved.",
"Moving focus to a success alert; move focus only to an error summary after a failed submit."
],
"doDont": [
{
"do": {
"text": "Give every toned alert its icon and a hidden severity prefix, so it never relies on color.",
"html": "
\n \n
\n
Warning: Your trial ends on 12 October 2026
\n
Choose a plan to keep your projects.
\n
\n
"
},
"dont": {
"text": "Don't signal severity with color alone: screen readers and people who can't tell the edge color apart miss it.",
"html": "
\n
\n
Your trial ends on 12 October 2026
\n
\n
",
"rule": "alert-severity"
}
},
{
"do": {
"text": "After a failed submit, list every error in an error alert, each linked to its field, and move focus to it.",
"html": "
"
},
"dont": {
"text": "Don't build an alert from elements outside the block: the tile and edge lose their shape.",
"html": "
\n
There is a problem
\n
",
"rule": "element-outside-block"
}
}
],
"content": [
"Titles say what happened in plain words, in sentence case, with no exclamation mark.",
"The text says what to do next. Name the action: \"Choose a plan\", not \"Click here\".",
"Keep the hidden prefix to one word and a colon: \"Error:\", \"Warning:\", \"Success:\", \"Information:\"."
]
},
"tokens": [
"--alert-background",
"--alert-border",
"--alert-edge-info",
"--alert-edge-success",
"--alert-edge-warning",
"--alert-edge-error"
],
"a11y": [
"Severity is carried three ways: the hidden text prefix, the icon shape and the bottom edge.",
"role=\"alert\" interrupts the screen reader: only for urgent messages that appear after an action.",
"An error summary gets tabindex=\"-1\" and focus after a failed submit; its links move focus to each field.",
"c-alert__close needs aria-label, and the app moves focus to a sensible place after hiding the alert."
],
"keyboard": [
{
"key": "Tab",
"action": "Moves through the links and buttons inside the alert, then the close button."
},
{
"key": "Enter",
"action": "Follows a link in an error summary to its field."
}
],
"related": [
"c-icon",
"c-form-field",
"c-modal",
"c-badge"
],
"examples": [
{
"file": "components/alert.html",
"html": "
The connection dropped. Check your network and save again.
\n
\n \n
\n
"
}
],
"sources": [
{
"title": "GOV.UK Design System: Error summary",
"url": "https://design-system.service.gov.uk/components/error-summary"
},
{
"title": "GOV.UK Design System: Notification banner",
"url": "https://design-system.service.gov.uk/components/notification-banner"
},
{
"title": "GitLab Pajamas: Alert",
"url": "https://design.gitlab.com/components/alert"
},
{
"title": "WAI-ARIA APG: Alert pattern",
"url": "https://www.w3.org/WAI/ARIA/apg/patterns/alert/"
},
{
"title": "Scott O'Hara: Are we live? (live regions)",
"url": "https://www.scottohara.me/blog/2022/02/05/are-we-live.html"
}
]
},
{
"name": "Badge",
"block": "c-badge",
"layer": "component",
"status": "stable",
"since": "0.1.0",
"description": "A short, non-interactive label for status or category, such as \"Beta\" or \"Paid\".",
"tags": [
"span"
],
"modifiers": [
{
"group": "tone",
"exclusive": true,
"values": [
{
"name": "primary",
"description": "Brand emphasis, e.g. \"New\"."
},
{
"name": "success",
"description": "Positive status, e.g. \"Active\"."
},
{
"name": "warning",
"description": "Needs attention, e.g. \"Expiring\"."
},
{
"name": "error",
"description": "Negative status, e.g. \"Failed\"."
},
{
"name": "info",
"description": "Neutral information, e.g. \"Draft\"."
}
]
}
],
"guidelines": {
"whenToUse": [
"Showing the status of an item: Draft, Active, Failed.",
"A short category or plan label: Beta, Pro."
],
"whenNotToUse": [
"Anything clickable, removable or filterable: use `c-button` with c-button--sm.",
"A count on a navigation item: badges here are for status words, not numbers.",
"A sentence: use body text or an alert."
],
"use": [
"Keep badge text to one or two words.",
"Group several badges with l-cluster."
],
"avoid": [
"Making a badge clickable; use c-button--sm instead.",
"Relying on badge color alone to convey meaning; the text must carry the status."
],
"doDont": [
{
"do": {
"text": "Say the status in words; the tone only supports it.",
"html": "
\n Failed\n Passed\n
"
},
"dont": {
"text": "Don't make a badge clickable or invent tones.",
"html": "Failed",
"rule": "unknown-class"
}
}
],
"content": [
"One or two words, sentence case: \"In review\", not \"IN REVIEW\".",
"Each tone keeps one meaning across the product: error always means something failed."
]
},
"tokens": [
"--badge-background",
"--badge-text",
"--color-action-primary",
"--color-text-on-action"
],
"a11y": [
"Color is decorative; the badge text must describe the status on its own."
],
"related": [
"l-cluster",
"c-card"
],
"examples": [
{
"file": "components/badge.html",
"html": "