dowel-ui 0.4.0 → 0.6.0

package/README.md

@@ -8,7 +8,10 @@ The lacodda line design system: theme tokens and React primitives, distributed a
 
 A dowel is the hidden peg that joins two boards so the seam does not show. That is what this does for the products of the line: they look made by one hand, and nobody sees the joint.
 
-**Status:** v0.4.0 - the theme, the scales, an accent per product, and the first primitive. See the [roadmap](#roadmap).
+**[Documentation](https://lacodda.github.io/dowel/)** — what everything is and why it is that way.
+**[The stand](https://lacodda.github.io/dowel/stand/)** — every component, live, in either theme and in the accent of any product of the line.
+
+**Status:** v0.6.0 - the theme, the scales, an accent per product, ten primitives and the lint rule that keeps them honest. The first product of the line lives on it. See the [roadmap](#roadmap).
 
 ## The theme
 
@@ -80,9 +83,24 @@ your code:
 npx shadcn@latest add https://lacodda.github.io/dowel/r/button.json
 ```
 
+Ten of them so far: Button, Input, Textarea, Panel, Badge, Chip, Kbd, Spinner,
+Truncate and Copyable.
+
 Each is written in the vocabulary - no raw colours, no `dark:` utilities - so
 the same component is correct in both themes and in every product's accent.
-Every one of them is shown live on [the stand](https://lacodda.github.io/dowel/components/button/), in both themes at once.
+Every one of them is on [the stand](https://lacodda.github.io/dowel/stand/), live - change the theme and the accent and watch what follows.
+
+That convention is a lint rule, and it ships with the package:
+
+```js
+// eslint.config.js
+import dowel from 'dowel-ui/eslint'
+
+export default [...dowel.configs.recommended]
+```
+
+It reports a hex, an `rgb()`, a stock Tailwind colour, `bg-white`, and any
+`dark:` utility, in the file that wrote one - see [the guide](https://lacodda.github.io/dowel/guides/linting/).
 
 Full vocabulary, shown rather than tabulated: **[colours](https://lacodda.github.io/dowel/reference/tokens/)** in both themes, **[the scales](https://lacodda.github.io/dowel/reference/scales/)** - radius, type, motion, elevation and stacking order - and **[the accents](https://lacodda.github.io/dowel/reference/accents/)**, where the same screen is drawn in every colour of the line.
 
@@ -102,9 +120,10 @@ Development goes in versions; each one is a single coherent theme, and ends in a
 
 ## Documentation
 
-- [Getting started](https://lacodda.github.io/dowel/getting-started/)
+- [The stand](https://lacodda.github.io/dowel/stand/) - every component, live
+- [Getting started](https://lacodda.github.io/dowel/getting-started/) and [the lint rule](https://lacodda.github.io/dowel/guides/linting/)
 - [Components](https://lacodda.github.io/dowel/components/button/)
-- [Token reference](https://lacodda.github.io/dowel/reference/tokens/)
+- [Tokens](https://lacodda.github.io/dowel/reference/tokens/), [scales](https://lacodda.github.io/dowel/reference/scales/) and [accents](https://lacodda.github.io/dowel/reference/accents/)
 
 ## License
 

package/dist/eslint/index.d.ts

@@ -0,0 +1,12 @@
+import type { ESLint, Linter } from 'eslint';
+/** The plugin, with its config bundled on - the shape flat config expects
+ * from a default export. Annotated rather than inferred: the inferred type
+ * reaches into ESLint's internals and cannot be written down by a consumer. */
+declare const dowel: ESLint.Plugin & {
+    configs: {
+        recommended: Linter.Config[];
+    };
+};
+export default dowel;
+export { noRawColor, findRawColor } from './no-raw-color.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/eslint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/eslint/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAoC5C;;+EAE+E;AAC/E,QAAA,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,GAAG;IAAE,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;KAAE,CAAA;CAEtE,CAAA;AAEF,eAAe,KAAK,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/eslint/index.js

@@ -0,0 +1,40 @@
+import { noRawColor } from './no-raw-color.js';
+/*
+ * The dowel ESLint plugin.
+ *
+ * One rule, and it enforces the convention the whole system rests on: a
+ * component names colours from the vocabulary and never writes one down.
+ *
+ * It ships from the package rather than the registry because it is not a
+ * component - it is not copied into a product and edited there, it is a check
+ * every product runs the same way, and it should improve for all of them at
+ * once.
+ *
+ *   import dowel from 'dowel-ui/eslint'
+ *
+ *   export default [
+ *     ...dowel.configs.recommended,
+ *   ]
+ */
+const plugin = {
+    meta: { name: 'dowel' },
+    rules: { 'no-raw-color': noRawColor },
+};
+/** The rule, applied where components live. Scoped to TypeScript sources: the
+ * theme is CSS and the build tools are Node, and neither is a component. */
+const recommended = [
+    {
+        files: ['**/*.{ts,tsx}'],
+        plugins: { dowel: plugin },
+        rules: { 'dowel/no-raw-color': 'error' },
+    },
+];
+/** The plugin, with its config bundled on - the shape flat config expects
+ * from a default export. Annotated rather than inferred: the inferred type
+ * reaches into ESLint's internals and cannot be written down by a consumer. */
+const dowel = Object.assign(plugin, {
+    configs: { recommended },
+});
+export default dowel;
+export { noRawColor, findRawColor } from './no-raw-color.js';
+//# sourceMappingURL=index.js.map

package/dist/eslint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/eslint/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;IACvB,KAAK,EAAE,EAAE,cAAc,EAAE,UAAU,EAAE;CACd,CAAA;AAEzB;4EAC4E;AAC5E,MAAM,WAAW,GAAoB;IACnC;QACE,KAAK,EAAE,CAAC,eAAe,CAAC;QACxB,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;QAC1B,KAAK,EAAE,EAAE,oBAAoB,EAAE,OAAO,EAAE;KACzC;CACF,CAAA;AAED;;+EAE+E;AAC/E,MAAM,KAAK,GAAkE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE;IACjG,OAAO,EAAE,EAAE,WAAW,EAAE;CACzB,CAAC,CAAA;AAEF,eAAe,KAAK,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/eslint/no-raw-color.d.ts

@@ -0,0 +1,11 @@
+import type { Rule } from 'eslint';
+interface Finding {
+    message: string;
+}
+/** What is wrong with this string, if anything. Exported for the test: the
+ * matching is the whole rule, and testing it directly is what lets a mutation
+ * to any single pattern show up as a failure. */
+export declare function findRawColor(text: string): Finding | undefined;
+export declare const noRawColor: Rule.RuleModule;
+export {};
+//# sourceMappingURL=no-raw-color.d.ts.map

package/dist/eslint/no-raw-color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-raw-color.d.ts","sourceRoot":"","sources":["../../src/eslint/no-raw-color.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AA2DlC,UAAU,OAAO;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;iDAEiD;AACjD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAgC9D;AAED,eAAO,MAAM,UAAU,EAAE,IAAI,CAAC,UA2B7B,CAAA"}

package/dist/eslint/no-raw-color.js

@@ -0,0 +1,109 @@
+/*
+ * `no-raw-color` - the rule behind the line's oldest convention.
+ *
+ * Two things are forbidden in a component, and they are the same mistake seen
+ * from either end:
+ *
+ *   - a raw colour (`#d9569e`, `rgb(...)`, `bg-zinc-800`), because a colour
+ *     without a name in the vocabulary cannot follow the product's accent and
+ *     will not swap when the theme does;
+ *   - a `dark:` utility, because it says the component knows which theme it is
+ *     in. It does not, and must not: the token underneath changes instead.
+ *
+ * The check is deliberately textual. What matters is what ends up in a
+ * `className`, and that string is assembled from literals in `cva` variant
+ * maps, ternaries and template pieces - places a type-aware rule would have to
+ * follow anyway. So every string literal in the file is read, and the ones
+ * that look like a colour are reported.
+ *
+ * It runs on components, not on the theme: the theme is where raw colour is
+ * supposed to live, and it is CSS, which this never sees.
+ */
+/** A hex colour: `#abc`, `#aabbcc`, `#aabbccdd`. Word-bounded at the end so a
+ * hash-prefixed word (`#section-title`) is not mistaken for one. */
+const HEX = /#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{1,5})?\b/;
+/** A CSS colour function with numeric arguments. `color-mix` and `oklch(from
+ * var(--accent-base) ...)` are how the theme derives colour and are allowed -
+ * what is forbidden is naming a colour outright. */
+const COLOR_FUNCTION = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab)\s*\(/;
+/** Tailwind's stock palette, as it appears inside a utility: `bg-zinc-800`,
+ * `hover:text-red-500/50`, `border-slate-200`. The line drops the stock
+ * palette from the theme, so these do not compile - but they are written by
+ * habit and by every code generator, and the error they produce points at CSS
+ * rather than at the file that asked. */
+const STOCK_PALETTE = /\b(?:slate|gray|grey|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|100|200|300|400|500|600|700|800|900|950)\b/;
+/** A `dark:` variant, anywhere in a class string. */
+const DARK_VARIANT = /(?:^|[\s"'`])dark:/;
+/*
+ * `white` and `black` as Tailwind utilities, at full opacity: `bg-white`,
+ * `text-black`. They are colours with no name in the vocabulary and no way to
+ * follow a theme - white chrome stays white when the ground turns white.
+ *
+ * With an opacity they are something else, and allowed: `bg-black/50` is a
+ * modal scrim, `text-white/70` is a label over a picture. Neither is a theme
+ * colour that failed to be named - they are what a translucent veil and ink
+ * on an arbitrary image are made of, which is why the theme keeps
+ * `--color-white` and `--color-black` deliberately. The line's first consumer
+ * had eleven of them and every one was right.
+ */
+const ABSOLUTE = /\b(?:bg|text|border|fill|stroke|ring|outline|divide|shadow|from|via|to)-(?:white|black)\b(?!\/)/;
+/** What is wrong with this string, if anything. Exported for the test: the
+ * matching is the whole rule, and testing it directly is what lets a mutation
+ * to any single pattern show up as a failure. */
+export function findRawColor(text) {
+    if (DARK_VARIANT.test(text)) {
+        return {
+            message: 'A `dark:` utility makes the component know which theme it is in. Use a token - the theme swaps it underneath.',
+        };
+    }
+    if (HEX.test(text)) {
+        return {
+            message: 'A raw colour cannot follow the product accent or the theme. Use a token from the dowel vocabulary.',
+        };
+    }
+    if (COLOR_FUNCTION.test(text)) {
+        return {
+            message: 'A raw colour cannot follow the product accent or the theme. Use a token from the dowel vocabulary.',
+        };
+    }
+    if (STOCK_PALETTE.test(text)) {
+        return {
+            message: "Tailwind's stock palette is dropped from the theme, so this compiles to nothing. Use a token from the dowel vocabulary.",
+        };
+    }
+    if (ABSOLUTE.test(text)) {
+        return {
+            message: '`white` and `black` do not change with the theme. Use `text-text`, `bg-bg` or another token.',
+        };
+    }
+    return undefined;
+}
+export const noRawColor = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Forbid raw colours and `dark:` utilities in components; every colour goes through a dowel token.',
+            url: 'https://lacodda.github.io/dowel/guides/tokens/',
+        },
+        schema: [],
+    },
+    create(context) {
+        const report = (node, text) => {
+            const finding = findRawColor(text);
+            if (finding)
+                context.report({ node, message: finding.message });
+        };
+        return {
+            Literal(node) {
+                if (typeof node.value === 'string')
+                    report(node, node.value);
+            },
+            TemplateElement(node) {
+                // A template element carries no cooked value when the template is
+                // tagged with an invalid escape; the raw text is always there.
+                report(node, node.value.cooked ?? node.value.raw);
+            },
+        };
+    },
+};
+//# sourceMappingURL=no-raw-color.js.map

package/dist/eslint/no-raw-color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-raw-color.js","sourceRoot":"","sources":["../../src/eslint/no-raw-color.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;oEACoE;AACpE,MAAM,GAAG,GAAG,wCAAwC,CAAA;AAEpD;;oDAEoD;AACpD,MAAM,cAAc,GAAG,0CAA0C,CAAA;AAEjE;;;;yCAIyC;AACzC,MAAM,aAAa,GACjB,gMAAgM,CAAA;AAElM,qDAAqD;AACrD,MAAM,YAAY,GAAG,oBAAoB,CAAA;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,QAAQ,GACZ,iGAAiG,CAAA;AAMnG;;iDAEiD;AACjD,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EACL,+GAA+G;SAClH,CAAA;IACH,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EACL,oGAAoG;SACvG,CAAA;IACH,CAAC;IACD,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EACL,oGAAoG;SACvG,CAAA;IACH,CAAC;IACD,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO,EACL,yHAAyH;SAC5H,CAAA;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,OAAO,EACL,8FAA8F;SACjG,CAAA;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAoB;IACzC,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS;QACf,IAAI,EAAE;YACJ,WAAW,EACT,kGAAkG;YACpG,GAAG,EAAE,gDAAgD;SACtD;QACD,MAAM,EAAE,EAAE;KACX;IACD,MAAM,CAAC,OAAO;QACZ,MAAM,MAAM,GAAG,CAAC,IAAe,EAAE,IAAY,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;YAClC,IAAI,OAAO;gBAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;QACjE,CAAC,CAAA;QAED,OAAO;YACL,OAAO,CAAC,IAAI;gBACV,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;oBAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;YAC9D,CAAC;YACD,eAAe,CAAC,IAAI;gBAClB,kEAAkE;gBAClE,+DAA+D;gBAC/D,MAAM,CAAC,IAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YAChE,CAAC;SACF,CAAA;IACH,CAAC;CACF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dowel-ui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The lacodda line design system: theme tokens and React primitives, distributed as a shadcn-compatible registry.",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,8 @@
     "react",
     "tailwindcss",
     "shadcn",
-    "registry"
+    "registry",
+    "eslint-plugin"
   ],
   "sideEffects": [
     "*.css"
@@ -33,18 +34,23 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./eslint": {
+      "types": "./dist/eslint/index.d.ts",
+      "import": "./dist/eslint/index.js"
+    },
     "./theme.css": "./dist/theme.css",
     "./tokens.json": "./dist/tokens.json",
     "./accents/*.css": "./dist/accents/*.css"
   },
   "scripts": {
-    "build": "tsc && node ../../tools/copy-theme.mjs && node ../../tools/build-tokens-json.mjs && node ../../tools/build-accents.mjs && node ../../tools/build-registry.mjs && node ../../tools/build-stand-theme.mjs",
+    "build": "tsc && node ../../tools/copy-theme.mjs && node ../../tools/build-tokens-json.mjs && node ../../tools/build-accents.mjs && node ../../tools/build-registry.mjs",
     "typecheck": "tsc --noEmit",
     "prepack": "node ../../tools/copy-readme.mjs"
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "eslint": "^9.0.0 || ^10.0.0"
   },
   "devDependencies": {
     "@radix-ui/react-slot": "^1.3.3",
@@ -52,6 +58,7 @@
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "class-variance-authority": "^0.7.1",
+    "eslint": "^10.9.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8"
   },
@@ -62,5 +69,10 @@
   "dependencies": {
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.6.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
   }
 }