![\"CI\"](\"https://github.com/ecoma-io/loom/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Analysis\"](\"https://img.shields.io/badge/analysis-semgrep-purple.svg\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/license-Apache--2.0-blue.svg\"){kind=icon}
\n ![\"Node](\"https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg\"){kind=icon}
= 24\" />\n ![\"pnpm](\"https://img.shields.io/badge/pnpm-11-f69220.svg\"){kind=icon}
\n ![\"TypeScript](\"https://img.shields.io/badge/TypeScript-strict-3178c6.svg\"){kind=icon}
\n ![\"Pull](\"https://img.shields.io/badge/PRs-welcome-7C3AED.svg\"){kind=icon}
\n\n \n \n \n
\n = 24\" />\n \n \n \n
\n ![\"Loom](\".github/assets/banner.png\")
\n
\n An Application Interface System for Vue.
\n An open-source, accessibility-first component library and design-token system —\n Vue 3, TypeScript and Tailwind CSS.
\n Build the interface once. Never re-decide what a button is.\n
\n Documentation →\n
\n\n---\n\n## What Loom is\n\nA design system is not a folder of components. It is a decision, made once, that\nevery screen inherits — how far apart two things sit, how a dialog gives focus\nback, what \"destructive\" looks like at 3am on a low-contrast monitor. Hand that\ndecision to each product and it is not made once. It is made again, slightly\ndifferently, every sprint, by whoever is closest to the deadline.\n\n**Loom is where that decision lives.** One vocabulary of design tokens, one set\nof accessible UI primitives, one motion language — consumed by every surface,\nowned by none of them.\n\n**Loom owns interface decisions, not application decisions.** What it standardises\nis the reusable layer — visual language, accessibility, interaction semantics,\nresponsive behaviour, composition, patterns, templates. What requires knowing\nwhat your product _is_ belongs to your product. That split is the one rule that\ndecides most questions about what belongs here.\n\n| | |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Design tokens** | Colour, spacing, radius, elevation, typography and motion — one source that light mode and dark mode both read from, so a rebrand is an edit rather than an audit. |\n| **UI primitives** | The generic controls every product needs and no product should own: buttons, inputs, selects, dialogs, menus, toasts, tooltips, skeletons, switches, progress. |\n| **Composition primitives** | Layout building blocks — Stack, Grid, Split, Center, Sidebar — that express spatial intent and adapt to viewport without the host writing breakpoint queries. |\n| **Patterns** | Compositions worth standardising once — empty states, page headers, title bars, sidebar navigation — assembled from primitives, never from scratch. |\n| **Showcase** | Demonstrations, in this documentation site, of what the parts produce when they compose — for discovery and teaching. A showcase is read; it is not a starting point to copy. |\n| **Templates** | Copyable prebuilt pages — Starter, Analytics, Workspace settings — to take into an application and build on. One page each; routing, auth and backend stay with the consumer. |\n| **Accessibility, built in** | Keyboard paths, focus restoration, accessible names and reduced-motion behaviour ship inside the component. WCAG is the acceptance bar, not a checklist run afterwards. |\n| **Theming that survives** | Every visual decision is a token reference, so white-labelling a tenant is configuration rather than a fork. |\n| **Typed and tree-shakeable** | Ships ES modules with TypeScript types. Consumers bundle what they import and nothing more. |\n\nIt is for teams building Vue applications who want the interface layer decided:\ndesign-system maintainers who want the token model, the artifact conventions and\nthe accessibility bar readable in the open, and anyone tired of re-deciding what\na button is — ship the defaults, override the tokens that don't fit, leave the\nrest alone. Loom originated within the [Ecoma](https://ecoma.io) ecosystem and is\ndeveloped as an independent open-source UI system.\n\n## Install\n\nLoom ships as one npm package — the components, the theme composable and the\nstylesheet entry behind a single install:\n\n```bash\npnpm add @ecoma-io/loom\n```\n\nOne import is the whole styling surface a normal host needs — tokens, the\nself-hosted fonts, base element styling and the motion library ride along:\n\n```css\n@import \"@ecoma-io/loom/styles/global.css\";\n```\n\nIt needs Vue 3.5 or newer as a peer and Tailwind CSS 4 in your build; the\n[compatibility table](#compatibility-and-requirements) has the full list. The\n[documentation site](https://ecoma.io/docs/contribute/design-system/) walks an\nempty Vue application to a rendered, themed component.\n\n## Your first component\n\n```vue\n\n\n\n \n\n```\n\nEverything importable lives behind the one package: [packages/loom/src/index.ts](packages/loom/src/index.ts)\nis the complete export list, and says so in its own docblock. The generic controls\nsit beside composition primitives that adapt to viewport and container — a\nsidebar collapses at the right width, a master-detail panel stacks on mobile,\nand on an ultrawide monitor content is bounded at readable widths, the extra\nviewport going to intentional whitespace rather than stretching.\n\nA `class` you pass merges with the component's own instead of replacing it —\n`cn` ships from the same package and is Tailwind-aware, so your `px-4` resolves\nagainst the component's `px-6` rather than both shipping and stylesheet order\ndeciding the winner.\n\nEach component's page on the documentation site carries an API table generated\nfrom the component's own `defineProps`, so the documented surface cannot drift\nfrom the shipped one.\n\n## Tokens and theming\n\nEvery visual decision is a token reference, and the tokens have one home:\n[packages/theme-core/src/theme.css](packages/theme-core/src/theme.css) is the\nsource of truth. Light mode and dark mode both derive from that one set — dark\nis not a second theme anyone maintains, which is why the two cannot drift apart.\nA `useTheme` composable switches between light, dark and system preference.\n\nBecause a token is a CSS custom property rather than a Tailwind class, the token\nlayer is framework-neutral and usable anywhere; the components that consume it\nare Vue. Rebranding is editing tokens; white-labelling a tenant is configuration,\nnot a fork.\n\n## The accessibility bar\n\nAccessibility ships inside the component, not as a follow-up: keyboard operation\nwith visible focus, focus restored to the trigger when an overlay closes,\naccessible names, no state conveyed by colour alone, and a\n`prefers-reduced-motion` path through the motion library.\n\nThe bar is defined, not aspirational. `WCAG_TAGS` in\n[packages/core/src/a11y-scope.ts](packages/core/src/a11y-scope.ts) is the closed\nrule set the library holds itself to — the axe rules mapping to a WCAG Level A\nor AA success criterion — and the browser gate that enforces it carries no\nexcludes. Every component also declares an `a11y.json` claim beside its source,\nheld by a gate against the role → requirement matrix in\n[packages/core/src/a11y-contract.ts](packages/core/src/a11y-contract.ts), so a\nrequirement nothing answers yet is recorded as a named exception rather than\nsilently missing. An accessibility bug is a bug, and it is filed and fixed as one.\n\n## Evidence tiers\n\nThe claims above are pinned at three runtimes — the same three the\naccessibility contract names (`browserless`, `harness`, `sweep`):\n\n- **browserless** — the jsdom sweep mounts every demo and holds it to its\n component's accessibility claim, no browser required.\n- **harness** — a Vite dev server mounts one demo at a time, so a component's\n browser specs run in seconds without paying for a site build.\n- **sweep** — the site-wide suite over the built documentation site: axe,\n contrast, target size, keyboard, focus-not-obscured, motion, responsive.\n\nBeside them, unit and integration tests live next to each component's source and\nthe browser tier lives apart; [CONTRIBUTING.md](CONTRIBUTING.md) holds the\ncontract for all of it. The documentation is held to the same honesty: token\ntables are generated from `theme.css` and API tables from the components\nthemselves — generated, never transcribed, so a page cannot quietly disagree\nwith the code it describes.\n\n## Templates\n\nAn Official Template is a copyable prebuilt **page** — a starting point composed\nfrom Loom components and patterns, taken into an application and built on:\nStarter, Analytics, Workspace settings. Where a pattern is a component you\ncompose with and the showcase is a demonstration you read, a template is a page\nyou start from. Routing, auth and backend stay with the consumer.\n\nTemplates consume the public `@ecoma-io/loom` package exactly as an external\nconsumer would — no internal imports, nothing the published package does not\nhave — because if a template cannot build against the published surface, that is\na defect in the surface. [docs/templates/contract.md](docs/templates/contract.md)\nstates the artifact kind's law, and the template suite holds every template to\nsmoke, axe in light and dark, keyboard and responsive gates.\n\n## Module boundaries\n\nLoom is layered, and the direction is one way: core → labels → primitives →\ncomposition → patterns → layouts → facade. The facade — the `@ecoma-io/loom`\npackage you install — is the only import surface: its exports map offers the\ncomponents, the `./a11y` and `./theme` entries, and the stylesheet files, and\nnothing inside the monorepo is public API.\n\nThe boundary is enforced twice, by two readers that see different things:\n[tools/check-architecture.ts](tools/check-architecture.ts) matches the import\nspecifier text, and [archkeep](https://github.com/ecoma-io/archkeep) resolves\neach specifier through the TypeScript config and judges the resolved target\nagainst [module-boundaries.config.mjs](module-boundaries.config.mjs). The\n[architecture contract](docs/architecture/contract.md) records which invariant\neach reader owns.\n\n## Governance and contributing\n\nWhat Loom takes is decided by the one rule: Loom holds what is **generic** — an\naffordance more than one product reaches for the same way. Everything else about\nworking here is the contract, and the contract is\n[CONTRIBUTING.md](CONTRIBUTING.md): the commit format, the test tiers, the\nSemgrep rules, the accessibility bar, and how a pull request lands.\n\nTo work on Loom itself:\n\n```bash\ngit clone https://github.com/ecoma-io/loom.git\ncd loom\npnpm install\n```\n\n`pnpm install` also installs the Git hooks, so formatting, linting and commit\nmessage checks run before anything reaches a branch. The component surface is\nlanding in the open, one artifact at a time — follow along or ask for something\nspecific in [the issues](https://github.com/ecoma-io/loom/issues).\n\nEveryone taking part is held to the [Code of Conduct](CODE_OF_CONDUCT.md).\nSecurity issues go through [SECURITY.md](SECURITY.md) — never a public issue.\n\nLoom is [Apache-2.0](LICENSE) — an explicit patent grant, which for a component\nlibrary that ends up embedded in commercial products is the difference between\n\"probably fine\" and \"written down\" — with no runtime dependency on any Ecoma\nplatform, so consuming it as an ordinary npm package includes consuming it\noutside Ecoma. Use it, ship it, fork it, sell what you build with it.\n\n## Compatibility and requirements\n\n| Requirement | Version |\n| ------------ | ---------------------------------------------- |\n| Node | ≥ 24 (`engines` in `package.json`) |\n| pnpm | 11 — pinned, so Corepack fetches the right one |\n| Vue | ≥ 3.5, as a peer dependency |\n| Tailwind CSS | 4, in your build (`@tailwindcss/vite`) |\n\nTypes ship strict, and the package ships ES modules that tree-shake: consumers\nbundle what they import and nothing more.\n\nCross-platform is a design constraint, not the product category. Loom's\ninterface decisions are made so they can survive a change of rendering target —\na browser tab, an installed PWA, an Electron or Tauri desktop shell, a mobile\nwebview — and the platform-specific parts stay at the boundary, passed in by the\nhost rather than sniffed at runtime: window chrome, safe-area insets, PWA\noverlays. Loom today is a Vue-facing interface system, not a cross-platform\nframework.\n\n---\n\n\n ![\"\"](\".github/assets/logo.png\"){kind=logo}
\n \n An Ecoma open-source project ·\n Documentation ·\n Organisation ·\n Contribute\n \n