@santi020k/lumen-mcp 0.3.0 → 0.4.0

package/data/lumen-data.json

@@ -11,6 +11,7 @@
       "Avatar": "8919014913a38d94a33da2898d775feb109770345ed33fe4184fea34ad7162e3",
       "BackToTop": "1c53e690626c2e9eaed71fafde5ec065b39a943b63048ad9ccf24f0c16edaa68",
       "Badge": "7e2d3cafb52609251056230c8389c731acfdf55895b8cf5e7712b138ad05e09b",
+      "BarChart": "c58fadb0fe2335edbf022a6c0fa11cb77c474830ccc2fb97a775595054653f7b",
       "Breadcrumb": "07e39012551d5916abd2ae7f8266386907b889ddba41da2eee34af7f6fea6673",
       "Bubble": "40e168ca39bac88b431e6104659c315a85bedd6198dd59f3f26582021df538b4",
       "Button": "ec006af669eecd5011afabeaaf244eab3f090e9858e368d13109232a2ae26d06",
@@ -19,7 +20,7 @@
       "Callout": "c13fbded24bcea45c0a9f9ddccef8cec4f4ed39e07809d5ff2a850485397eb51",
       "Card": "e50266a9cf255a7a1706373b5859272dd17ba0e57fd7aff37f2a7ac35797c669",
       "Carousel": "811a7ca777563b88766a6ae97a796ba789c7fb22ab06f253773e280ba5804a38",
-      "Chart": "bf9cf9fdfcf44837369968e6b55a89c09e5d1aa9e283c9f2bab4c5589393c77f",
+      "Chart": "473c4e02c80803565f0409e4e4024c2e06c09f476a8bd13a118e75f2b2ddce1b",
       "Checkbox": "d971d97482ba924a07d4891cc782dd14c87b9f8bdb7b4070181b2189748b8be1",
       "Collapsible": "7652876be7a40fc2451168ea8220c49a5ef0fcfddc04d6d5ff424e6d2d26a04a",
       "Code": "e2f5eea415e1d2212dcb782487b417806f7ba6a7b1469f1b74a082fe35523275",
@@ -41,7 +42,7 @@
       "FloatingBadge": "db0fb0b64ba740b195c7ddebd6f0573ce3da25dbca7e80eb82fe0fb425e15d04",
       "FormattedDate": "c4f24887c4746220a641e34590e22434d08f02345abde6316246d76e77bacfb6",
       "HoverCard": "7600efb83ed7b3d71b8a12d073a408d8663fb0b644b64e35d2c9b113a4130473",
-      "Icon": "947d13b473c0124e849d46bffe0b2a06b09cd505414d1469c6f4f54e07511cc0",
+      "Icon": "a8957b7c35f2bce93c240e7a420e96fecdd47f548583f9a87808fb2a8a152e09",
       "Image": "ae96c90e196f84f026fc0298a29b167a31b04599a5d229bccd01e6118f811649",
       "Input": "a928bc600c02646eae2162bb4ebe292d54a30a13107dda6c5b1152fa47619340",
       "InputGroup": "ce2011ca129f23c62f0dd34e75d2b8f15437fbc72bd95d77ad1e4d7de1124754",
@@ -50,6 +51,7 @@
       "Kbd": "28e109087067cc5c71a4fd84c9add36be7de7a39ce376d3ef59fc8d9465ecee1",
       "Label": "e76c47b92db619d66ce76c15f10e440c599c2759cb96c328d2bbd0d75659ef92",
       "Link": "c3e950ce51c641e6593868d99aea43936cd35b8559127dd3b881b04f4aa565a0",
+      "LineChart": "b4f03a5cd9bd8bfff94d4182163630af5939ba6b67508b778d9422a51620617b",
       "Marker": "4875fd7e8792aac78bb6b3733a48d0a2f1c298d812db89c0680d736bf4c07a15",
       "Menubar": "5450c01fa81f0b9dce4d1f39ce7507f6d744b2147cfa68d859e8e02714e2f16c",
       "Message": "f7f25f4c9e727d83af8b4c42751d024f7de418d45771ba3a975ac229d332cb7c",
@@ -59,14 +61,16 @@
       "NumberField": "97db5294f8232c25958c15bf93e2c78caf55651a5cc9439e3de6eb58e727e9bf",
       "Pagination": "79afd85add73b34c6c6f954b7755ee8e795b8836bee6193efc22910bdeb9f333",
       "PhoneInput": "585a257a1cc654fa653c7bd81a400ce8991f71a9d67596c3b2511ea9b8d83614",
-      "Pill": "92fc30d63bb36ef025736d99047bfc0d3f17cb76a69f6dafdac0d7e3d9b735b0",
+      "PieChart": "19eae80895734a9f5be30f8ff66ba87b7d1e7b438df3195efcd738e7f82a932c",
+      "Pill": "bbab3e93037d35258eff820a57892bf6002dd2cbcebb8241866da89e30d8b52c",
       "Popover": "a596714668a14c81c2e6edf7666ca2cc17939c057470cc90c10a18a13924c401",
-      "Progress": "a3ea401bfcdf39ca151bc142981db105865b1a5da92dd999e50efc14f13c259a",
+      "Progress": "405786d7a0e5681adfa520df338957d6d486db14006e5aab652b1822a78bc26d",
       "Prose": "14454809f9ae5e0b509418fa1d74d00af480b5ce2d289e7c608c1ad78ef93eff",
       "RadioGroup": "5f9bd9181f6fd47d3c168846cc21eed2308064535bc527e8fc1a60460b3138fb",
       "Resizable": "36d3a5b19ec3eb74e8ebfdd92a7e0105a1deb115142c76df1784ce5a8f4bdb61",
       "RichTextEditor": "dbc639a21744cf725ae78c3dfe90c310285c34034f1a59ce42969f46d651539f",
       "ScrollArea": "a0b2ea629429009e7b51bf33ab256150f320c5704370347ce16a70a84d627c55",
+      "ScrollProgress": "071a889086890c45934369fbb85c65a49cefc238c522aadd4723cb48505ad01e",
       "Schedule": "d1cb86cb6132a0352c75eaf3413d204dba48832ab385ce205c1e61d59633139c",
       "SearchField": "561a310b3c8b112ed1baa7a01783be4471d73b47f3f2800460b4ccc23ca7bf42",
       "Select": "2986d0d3dd9def947c418df15758bff6881d2a81fe1e1e68b6ef15d9b0dd19bc",
@@ -77,6 +81,7 @@
       "SkipLink": "d660feaa0edbfdbb72d6da0c2bb62e725448ee4ff75ac1b34588cf4ceb3dbcd8",
       "Slider": "cca90425ee92d9710e7b31d815d58027f2c3bcbd372282d20b6ef2fbd0aadb27",
       "Sonner": "a7767b9f7a4d5d8b7263c19a9833336ef965c8a697ae6607ccd5fee9a69c0529",
+      "Sparkline": "d3d21505eae092a9161a82c30599d30f86246c1c45e2c0755bf1ae323a02e5fe",
       "Spinner": "f5817573620b0fd870b2f0cca52c2baa1f00eb2f6d6a8087fe2f2db3e0051ff2",
       "Switch": "046af1a323a3f49f7e83cae17c9eceac80afb8fa5afe91478bd10a1f65e33e5a",
       "Table": "8481dc8028e49bae10d46ce66c29fb0fe06154ebbb7d66724749ff8d6f881d98",
@@ -95,12 +100,12 @@
       "Typography": "0bc81b7dd562a010f8a4892370fd7a4382e929cc3c9e504126d65c4d3da2c040",
       "VirtualList": "9f9277e3cc92a61cf35d2959a5ee08f01f627aee71fd9c3f1ffafb206b1f07e9",
       "LanguageToggle": "8f3cd99de808d9983e1ad304a7867d55505d51c7867e04ce7ba155aea59afb23",
-      "Particles": "6697278a3c6e795549f6c72ea59bcb70fab9af87f68f503c3703c9ad3c336632",
+      "Particles": "06b1b05dea30b0d0992835599ac18101b6d08c28bbe9e39139562d30db1c973f",
       "AnimatedNumber": "afbf3dfadcd3338199dbdc2d2e6c80182b90a3b6741ae4009f2ab68cf326235a",
       "RevealGroup": "57ef595e6aff5c7a2843054d18639466022b2bebad2da2ce6b14a4970757c484",
       "ScrollReveal": "940d69fc6bf5427c8bece747727872a8707c5b0c7fbefe60dad65d3b066ab35d",
-      "Stat": "7bee1666885e380bf59752abf9d78ccca9b027062af258e556cffc1f0792b013",
-      "Meter": "53461cc1804f08c63c1d0468f4169fa612696175b785946300fb63478df23330",
+      "Stat": "b46bde93ea058c24fb0a685b48ba3c85915e3506c6dfb0ba21e373619230b0b1",
+      "Meter": "19a209d62f2f68750bb4092130fbc9e8d1c33a11132eb5871110eba45f93af9f",
       "Note": "17c44fe3a3b08193ebba56b20d3d04f90f906b477e24a21c059b8531eac1aa16",
       "Rating": "ec00e1b7f39a38884922bd48490b1dd5625b2eb41ed5265cf83600f7705180b5",
       "Timeline": "93ffea4de7b9007c8a2badc99cf965fe7d974ae4ba5ad01c275183af5c3d6d79",
@@ -112,7 +117,7 @@
       "Stepper": "3974df2b0c0be37a1e0c1f69dd7ce77bd6655d0f7b03a86a8dbf61191193598d",
       "FileUpload": "91fa5aea1c3318c9b255ce2c700c014bc3ca98a54a2dfd599f7e3bfd5a0e5558",
       "Tour": "4a294319873159d566d1dfc1878937fd2338629f2c57702daa822c275de80110",
-      "Anchor": "7b787063895ffa21d6c412133ba94a5dfd4503bd3e2b4e656ac2174cd5b5d116",
+      "Anchor": "eb86f012637c44fba25025ceb667aec83899decd5e4833ff92e33e75090642b5",
       "Segmented": "fea2f68a5935678aa892e39ae4808dd2fc36be992215a1665e321594d4cd8755",
       "Toolbar": "eb3d645b5f843ad028122d6d5244b3c1eab8b4b6a25f2cec1ae4f56e72f009b8",
       "Descriptions": "5e1a8991654626fbe3fe541f299be774dfc2801313a49cbd4b11cf4eb31de983",
@@ -122,7 +127,7 @@
       "TreeSelect": "8d4b1475eab41f4e41b632dc535f31d6fe6fa44cbb6bbbebbdfed73eaefd3d35",
       "Mentions": "bf9b8f29f881ebe7022a28744ae8fcc63329e887f3bfd6d660708192e9f912cd",
       "QRCode": "ecd8c0488bc4ef147208627cc6d4298be62633e9293a0c5cd7f0835594c85d71",
-      "Watermark": "7eecfb10c2fbb045dcaf9a62a216d16c12af485d29879dcac24f989bf191ec0b",
+      "Watermark": "4e942660bb7dee0623c4d41553fd0e162b1e1f04f195e5a0b55eddae18bdbee3",
       "Affix": "4215241a8b0633eb191a00b50a875e10cb226ab7ef21f2f6842431d8f6acc3be",
       "SpeedDial": "b6a51b1715c92c4a2860759b146b4ceeab01acf326faeeb1e023a01e8b811fc9"
     },
@@ -132,7 +137,8 @@
       "scheduler": "fe25905d95e8d4294df9075e47ee9257d7db8e6542a3ac81272c4dee2ea1fdc0",
       "data-collections": "fbbc09e60caed2449b5b904f9f1432278b52c8d28e7fe22de30af21208a4dfaf",
       "theme-builder": "8de1d5f902b728af947f57e0f3667a5a8991ef71755bca7d985cdcaec9572252",
-      "rich-text-editor": "3c47135e8e10890e1d41b1878fdd497a5c87c34c5663821cf4005602cd7adbc9"
+      "rich-text-editor": "3c47135e8e10890e1d41b1878fdd497a5c87c34c5663821cf4005602cd7adbc9",
+      "data-visualization": "97f8f447cd36dfe026478f3eea379abe0907d5094f06285ec351c14a62908259"
     }
   },
   "components": [
@@ -1936,6 +1942,335 @@
       "recipes": [],
       "runtimeEvents": []
     },
+    {
+      "apiReference": [
+        {
+          "attribute": "glass",
+          "defaultValue": "false",
+          "description": "Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; \"subtle\" and \"strong\" adjust the fill intensity.",
+          "values": "boolean | \"subtle\" | \"strong\""
+        },
+        {
+          "attribute": "series",
+          "defaultValue": "required",
+          "description": "Provides already-aggregated categorical values and stable series metadata.",
+          "values": "LumenChartSeries[]"
+        },
+        {
+          "attribute": "orientation",
+          "defaultValue": "\"vertical\"",
+          "description": "Controls whether values extend across the x or y axis.",
+          "values": "\"horizontal\" | \"vertical\""
+        },
+        {
+          "attribute": "layout",
+          "defaultValue": "\"grouped\"",
+          "description": "Places series beside one another or combines their positive and negative totals.",
+          "values": "\"grouped\" | \"stacked\""
+        },
+        {
+          "attribute": "showLegend",
+          "defaultValue": "true for multiple series",
+          "description": "Shows the color-independent series key.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "showTable",
+          "defaultValue": "true",
+          "description": "Provides a revealable semantic table containing every plotted value.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "heading, description, caption",
+          "defaultValue": "-",
+          "description": "Adds visible chart context without replacing the accessible name.",
+          "values": "string"
+        },
+        {
+          "attribute": "class, className",
+          "defaultValue": "\"\"",
+          "description": "Merges custom classes with the generated ui-* root classes.",
+          "values": "string"
+        },
+        {
+          "attribute": "...native attributes",
+          "defaultValue": "-",
+          "description": "Forwards standard attributes to the root element unless the component consumes them.",
+          "values": "HTML attributes"
+        }
+      ],
+      "astroSource": "---\nimport {\n  createLumenBarGeometry,\n  getLumenChartTicks,\n  hasLumenChartData,\n  type LumenBarChartLayout,\n  type LumenChartOrientation,\n  type LumenChartSeries,\n  resolveLumenChartTone,\n  scaleLumenChartValue\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\nimport Chart from './Chart.astro'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  caption?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  layout?: LumenBarChartLayout\n  orientation?: LumenChartOrientation\n  series: readonly LumenChartSeries[]\n  showLegend?: boolean\n  showTable?: boolean\n}\n\nconst {\n  caption,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  layout = 'grouped',\n  orientation = 'vertical',\n  series,\n  showLegend = series.length > 1,\n  showTable = true,\n  ...rest\n} = Astro.props\nconst geometry = createLumenBarGeometry(series, { layout, orientation })\nconst hasData = hasLumenChartData(series)\nconst ticks = getLumenChartTicks(geometry.domain)\nconst categories = geometry.categories.map(category => category.label)\nconst valueFor = (item: LumenChartSeries, category: number | string) =>\n  item.data.find(datum => datum.x === category)?.y ?? null\nconst labelFor = (item: LumenChartSeries, category: number | string) =>\n  item.data.find(datum => datum.x === category)?.label\nconst margin = orientation === 'horizontal'\n  ? { bottom: 24, left: 112, right: 20, top: 16 }\n  : { bottom: 52, left: 52, right: 16, top: 16 }\n---\n\n<Chart\n  class:list={['ui-bar-chart', classProp, className]}\n  {caption}\n  {description}\n  {glass}\n  {heading}\n  {...rest}\n>\n  {\n    showLegend && hasData && (\n      <ul class=\"ui-chart__legend\" aria-label=\"Chart legend\">\n        {series.map((item, index) => (\n          <li class={`ui-chart-tone--${resolveLumenChartTone(item.tone, index)}`}>\n            <span aria-hidden=\"true\" />\n            {item.label}\n          </li>\n        ))}\n      </ul>\n    )\n  }\n  {!hasData && <p class=\"ui-chart__empty\" role=\"status\">No chart data available.</p>}\n  <div class=\"ui-chart__plot\" hidden={!hasData}>\n    <svg\n      aria-hidden=\"true\"\n      preserveAspectRatio=\"xMidYMid meet\"\n      viewBox={`0 0 ${geometry.width} ${geometry.height}`}\n    >\n      <g class=\"ui-chart__grid\">\n        {\n          ticks.map((tick) => {\n            const coordinate =\n              orientation === 'horizontal'\n                ? scaleLumenChartValue(\n                    tick,\n                    geometry.domain,\n                    margin.left,\n                    geometry.width - margin.right\n                  )\n                : scaleLumenChartValue(\n                    tick,\n                    geometry.domain,\n                    geometry.height - margin.bottom,\n                    margin.top\n                  )\n\n            return orientation === 'horizontal' ? (\n              <line\n                x1={coordinate}\n                x2={coordinate}\n                y1={margin.top}\n                y2={geometry.height - margin.bottom}\n              />\n            ) : (\n              <line\n                x1={margin.left}\n                x2={geometry.width - margin.right}\n                y1={coordinate}\n                y2={coordinate}\n              />\n            )\n          })\n        }\n      </g>\n      <g class=\"ui-chart__axis-labels\">\n        {\n          geometry.categories.map((category) => (\n            <text\n              dominant-baseline={orientation === 'horizontal' ? 'middle' : undefined}\n              text-anchor={orientation === 'horizontal' ? 'end' : 'middle'}\n              x={category.x}\n              y={category.y}\n            >\n              {String(category.label)}\n            </text>\n          ))\n        }\n      </g>\n      <g class=\"ui-bar-chart__marks\">\n        {\n          geometry.marks.map((mark) => (\n            <rect\n              class={`ui-chart-tone--${mark.tone}`}\n              height={mark.height}\n              rx=\"4\"\n              width={mark.width}\n              x={mark.x}\n              y={mark.y}\n            >\n              <title>\n                {`${String(mark.category)} · ${mark.seriesLabel}: ${mark.value}`}\n              </title>\n            </rect>\n          ))\n        }\n      </g>\n    </svg>\n  </div>\n  {\n    showTable && hasData && (\n      <details class=\"ui-chart__data\">\n        <summary>View chart data</summary>\n        <div>\n          <table>\n            <thead>\n              <tr>\n                <th scope=\"col\">Category</th>\n                {series.map(item => <th scope=\"col\">{item.label}</th>)}\n              </tr>\n            </thead>\n            <tbody>\n              {categories.map(category => (\n                <tr>\n                  <th scope=\"row\">{String(category)}</th>\n                  {series.map(item => (\n                    <td>\n                      {labelFor(item, category) ??\n                        String(valueFor(item, category) ?? 'Not available')}\n                    </td>\n                  ))}\n                </tr>\n              ))}\n            </tbody>\n          </table>\n        </div>\n      </details>\n    )\n  }\n</Chart>\n",
+      "category": "Data display",
+      "collections": [
+        "Data visualization"
+      ],
+      "dependencies": [
+        "Chart",
+        "styles"
+      ],
+      "description": "Compares categorical or discrete-period values with grouped and stacked bars.",
+      "files": [
+        "packages/astro/components/BarChart.astro",
+        "packages/astro/components/Chart.astro",
+        "packages/astro/styles/lumen.css"
+      ],
+      "frameworkDetails": {
+        "astro": {
+          "available": true,
+          "example": "<BarChart aria-label=\"Downloads by project\" heading=\"Package downloads\" orientation=\"horizontal\" series={[{ id: \"downloads\", label: \"Downloads\", data: [{ x: \"Lumen\", y: 18420 }, { x: \"Observatory\", y: 6320 }] }]} />",
+          "importStatement": "import { BarChart } from '@santi020k/lumen-astro'",
+          "language": "astro",
+          "packageName": "@santi020k/lumen-astro",
+          "props": [
+            {
+              "name": "caption",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "class",
+              "optional": true,
+              "type": "string | null"
+            },
+            {
+              "name": "className",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "description",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "glass",
+              "optional": true,
+              "type": "boolean | 'subtle' | 'strong'"
+            },
+            {
+              "name": "heading",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "layout",
+              "optional": true,
+              "type": "LumenBarChartLayout"
+            },
+            {
+              "name": "orientation",
+              "optional": true,
+              "type": "LumenChartOrientation"
+            },
+            {
+              "name": "series",
+              "optional": false,
+              "type": "readonly LumenChartSeries[]"
+            },
+            {
+              "name": "showLegend",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "showTable",
+              "optional": true,
+              "type": "boolean"
+            }
+          ],
+          "propsExtends": "HTMLAttributes<'figure'>",
+          "source": "---\nimport {\n  createLumenBarGeometry,\n  getLumenChartTicks,\n  hasLumenChartData,\n  type LumenBarChartLayout,\n  type LumenChartOrientation,\n  type LumenChartSeries,\n  resolveLumenChartTone,\n  scaleLumenChartValue\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\nimport Chart from './Chart.astro'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  caption?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  layout?: LumenBarChartLayout\n  orientation?: LumenChartOrientation\n  series: readonly LumenChartSeries[]\n  showLegend?: boolean\n  showTable?: boolean\n}\n\nconst {\n  caption,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  layout = 'grouped',\n  orientation = 'vertical',\n  series,\n  showLegend = series.length > 1,\n  showTable = true,\n  ...rest\n} = Astro.props\nconst geometry = createLumenBarGeometry(series, { layout, orientation })\nconst hasData = hasLumenChartData(series)\nconst ticks = getLumenChartTicks(geometry.domain)\nconst categories = geometry.categories.map(category => category.label)\nconst valueFor = (item: LumenChartSeries, category: number | string) =>\n  item.data.find(datum => datum.x === category)?.y ?? null\nconst labelFor = (item: LumenChartSeries, category: number | string) =>\n  item.data.find(datum => datum.x === category)?.label\nconst margin = orientation === 'horizontal'\n  ? { bottom: 24, left: 112, right: 20, top: 16 }\n  : { bottom: 52, left: 52, right: 16, top: 16 }\n---\n\n<Chart\n  class:list={['ui-bar-chart', classProp, className]}\n  {caption}\n  {description}\n  {glass}\n  {heading}\n  {...rest}\n>\n  {\n    showLegend && hasData && (\n      <ul class=\"ui-chart__legend\" aria-label=\"Chart legend\">\n        {series.map((item, index) => (\n          <li class={`ui-chart-tone--${resolveLumenChartTone(item.tone, index)}`}>\n            <span aria-hidden=\"true\" />\n            {item.label}\n          </li>\n        ))}\n      </ul>\n    )\n  }\n  {!hasData && <p class=\"ui-chart__empty\" role=\"status\">No chart data available.</p>}\n  <div class=\"ui-chart__plot\" hidden={!hasData}>\n    <svg\n      aria-hidden=\"true\"\n      preserveAspectRatio=\"xMidYMid meet\"\n      viewBox={`0 0 ${geometry.width} ${geometry.height}`}\n    >\n      <g class=\"ui-chart__grid\">\n        {\n          ticks.map((tick) => {\n            const coordinate =\n              orientation === 'horizontal'\n                ? scaleLumenChartValue(\n                    tick,\n                    geometry.domain,\n                    margin.left,\n                    geometry.width - margin.right\n                  )\n                : scaleLumenChartValue(\n                    tick,\n                    geometry.domain,\n                    geometry.height - margin.bottom,\n                    margin.top\n                  )\n\n            return orientation === 'horizontal' ? (\n              <line\n                x1={coordinate}\n                x2={coordinate}\n                y1={margin.top}\n                y2={geometry.height - margin.bottom}\n              />\n            ) : (\n              <line\n                x1={margin.left}\n                x2={geometry.width - margin.right}\n                y1={coordinate}\n                y2={coordinate}\n              />\n            )\n          })\n        }\n      </g>\n      <g class=\"ui-chart__axis-labels\">\n        {\n          geometry.categories.map((category) => (\n            <text\n              dominant-baseline={orientation === 'horizontal' ? 'middle' : undefined}\n              text-anchor={orientation === 'horizontal' ? 'end' : 'middle'}\n              x={category.x}\n              y={category.y}\n            >\n              {String(category.label)}\n            </text>\n          ))\n        }\n      </g>\n      <g class=\"ui-bar-chart__marks\">\n        {\n          geometry.marks.map((mark) => (\n            <rect\n              class={`ui-chart-tone--${mark.tone}`}\n              height={mark.height}\n              rx=\"4\"\n              width={mark.width}\n              x={mark.x}\n              y={mark.y}\n            >\n              <title>\n                {`${String(mark.category)} · ${mark.seriesLabel}: ${mark.value}`}\n              </title>\n            </rect>\n          ))\n        }\n      </g>\n    </svg>\n  </div>\n  {\n    showTable && hasData && (\n      <details class=\"ui-chart__data\">\n        <summary>View chart data</summary>\n        <div>\n          <table>\n            <thead>\n              <tr>\n                <th scope=\"col\">Category</th>\n                {series.map(item => <th scope=\"col\">{item.label}</th>)}\n              </tr>\n            </thead>\n            <tbody>\n              {categories.map(category => (\n                <tr>\n                  <th scope=\"row\">{String(category)}</th>\n                  {series.map(item => (\n                    <td>\n                      {labelFor(item, category) ??\n                        String(valueFor(item, category) ?? 'Not available')}\n                    </td>\n                  ))}\n                </tr>\n              ))}\n            </tbody>\n          </table>\n        </div>\n      </details>\n    )\n  }\n</Chart>\n",
+          "styleImport": "import '@santi020k/lumen-astro/styles.css'"
+        },
+        "elements": {
+          "attributes": [
+            "layout",
+            "orientation",
+            "glass",
+            "series",
+            "showLegend",
+            "showTable",
+            "heading, description, caption",
+            "class, className",
+            "...native attributes"
+          ],
+          "available": true,
+          "behavior": {
+            "mode": "registration",
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
+          },
+          "example": "<lumen-bar-chart></lumen-bar-chart>",
+          "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
+          "language": "html",
+          "packageName": "@santi020k/lumen-elements",
+          "props": [],
+          "propsExtends": "HTMLElement attributes",
+          "registration": "defineLumenElements()",
+          "source": "BarChart: {\n    attributeClasses: glassAttributeClasses('ui-chart--glass'),\n    baseClassName: 'ui-chart ui-bar-chart',\n    defaults: { layout: 'grouped', orientation: 'vertical' },\n    role: 'figure',\n    tagName: 'lumen-bar-chart'\n  }",
+          "styleImport": "import '@santi020k/lumen-elements/styles.css'",
+          "tagName": "lumen-bar-chart"
+        },
+        "react": {
+          "available": true,
+          "example": "<BarChart aria-label=\"Downloads by project\" heading=\"Package downloads\" orientation=\"horizontal\" series={[{ id: \"downloads\", label: \"Downloads\", data: [{ x: \"Lumen\", y: 18420 }, { x: \"Observatory\", y: 6320 }] }]} />",
+          "importStatement": "import { BarChart } from '@santi020k/lumen-react'",
+          "language": "tsx",
+          "packageName": "@santi020k/lumen-react",
+          "props": [
+            {
+              "name": "layout",
+              "optional": true,
+              "type": "LumenBarChartLayout"
+            },
+            {
+              "name": "orientation",
+              "optional": true,
+              "type": "LumenChartOrientation"
+            },
+            {
+              "name": "series",
+              "optional": true,
+              "type": "readonly LumenChartSeries[]"
+            },
+            {
+              "name": "showLegend",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "showTable",
+              "optional": true,
+              "type": "boolean"
+            }
+          ],
+          "propsExtends": "Omit<ChartProps, 'children'>",
+          "source": "export interface BarChartProps extends Omit<ChartProps, 'children'> {\n  layout?: LumenBarChartLayout\n  orientation?: LumenChartOrientation\n  series?: readonly LumenChartSeries[]\n  showLegend?: boolean\n  showTable?: boolean\n}\n\nexport const BarChart = ({\n  className,\n  layout = 'grouped',\n  orientation = 'vertical',\n  series = emptyChartSeries,\n  showLegend = series.length > 1,\n  showTable = true,\n  ...props\n}: BarChartProps) => {\n  const geometry = createLumenBarGeometry(series, { layout, orientation })\n  const hasData = hasLumenChartData(series)\n  const ticks = getLumenChartTicks(geometry.domain)\n  const categories = geometry.categories.map(category => category.label)\n\n  const margin = orientation === 'horizontal'\n    ? { bottom: 24, left: 112, right: 20, top: 16 }\n    : { bottom: 52, left: 52, right: 16, top: 16 }\n\n  return (\n    <Chart className={composeClassName('ui-bar-chart', className)} {...props}>\n      {showLegend && hasData && <ChartLegend series={series} />}\n      {!hasData && (\n        <p className=\"ui-chart__empty\" role=\"status\">No chart data available.</p>\n      )}\n      <div className=\"ui-chart__plot\" hidden={!hasData}>\n        <svg\n          aria-hidden=\"true\"\n          preserveAspectRatio=\"xMidYMid meet\"\n          viewBox={`0 0 ${geometry.width} ${geometry.height}`}\n        >\n          <g className=\"ui-chart__grid\">\n            {ticks.map(tick => {\n              const coordinate = orientation === 'horizontal'\n                ? scaleLumenChartValue(\n                    tick,\n                    geometry.domain,\n                    margin.left,\n                    geometry.width - margin.right\n                  )\n                : scaleLumenChartValue(\n                    tick,\n                    geometry.domain,\n                    geometry.height - margin.bottom,\n                    margin.top\n                  )\n\n              return orientation === 'horizontal' ? (\n                <line\n                  key={tick}\n                  x1={coordinate}\n                  x2={coordinate}\n                  y1={margin.top}\n                  y2={geometry.height - margin.bottom}\n                />\n              ) : (\n                <line\n                  key={tick}\n                  x1={margin.left}\n                  x2={geometry.width - margin.right}\n                  y1={coordinate}\n                  y2={coordinate}\n                />\n              )\n            })}\n          </g>\n          <g className=\"ui-chart__axis-labels\">\n            {geometry.categories.map(category => (\n              <text\n                dominantBaseline={orientation === 'horizontal' ? 'middle' : undefined}\n                key={`${typeof category.label}:${String(category.label)}`}\n                textAnchor={orientation === 'horizontal' ? 'end' : 'middle'}\n                x={category.x}\n                y={category.y}\n              >\n                {String(category.label)}\n              </text>\n            ))}\n          </g>\n          <g className=\"ui-bar-chart__marks\">\n            {geometry.marks.map(mark => (\n              <rect\n                className={`ui-chart-tone--${mark.tone}`}\n                height={mark.height}\n                key={`${mark.seriesId}:${String(mark.category)}`}\n                rx=\"4\"\n                width={mark.width}\n                x={mark.x}\n                y={mark.y}\n              >\n                <title>{`${String(mark.category)} · ${mark.seriesLabel}: ${mark.value}`}</title>\n              </rect>\n            ))}\n          </g>\n        </svg>\n      </div>\n      {showTable && hasData && (\n        <ChartDataTable categories={categories} series={series} />\n      )}\n    </Chart>\n  )\n}",
+          "styleImport": "import '@santi020k/lumen-react/styles.css'"
+        }
+      },
+      "frameworks": {
+        "astro": true,
+        "elements": true,
+        "react": true
+      },
+      "guidance": {
+        "when": "Use to compare categories, rankings, or discrete periods from already-aggregated values.",
+        "distinction": "Use LineChart for continuous ordered trends and Sparkline for a compact trend attached to one metric."
+      },
+      "kebab": "bar-chart",
+      "keyboardInteractions": [],
+      "keywords": [
+        "aggregated",
+        "already",
+        "and",
+        "attached",
+        "barchart",
+        "bars",
+        "breakdowns",
+        "categorical",
+        "categories",
+        "compact",
+        "compare",
+        "compares",
+        "comparisons",
+        "continuous",
+        "custom",
+        "data",
+        "discrete",
+        "display",
+        "for",
+        "from",
+        "grouped",
+        "linechart",
+        "match",
+        "metric",
+        "metrics",
+        "one",
+        "ordered",
+        "part",
+        "period",
+        "periods",
+        "plots",
+        "question",
+        "rankings",
+        "sparkline",
+        "stacked",
+        "the",
+        "trend",
+        "trends",
+        "use",
+        "values",
+        "visualization",
+        "whole",
+        "with"
+      ],
+      "name": "BarChart",
+      "props": [
+        {
+          "name": "caption",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "class",
+          "optional": true,
+          "type": "string | null"
+        },
+        {
+          "name": "className",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "description",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "glass",
+          "optional": true,
+          "type": "boolean | 'subtle' | 'strong'"
+        },
+        {
+          "name": "heading",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "layout",
+          "optional": true,
+          "type": "LumenBarChartLayout"
+        },
+        {
+          "name": "orientation",
+          "optional": true,
+          "type": "LumenChartOrientation"
+        },
+        {
+          "name": "series",
+          "optional": false,
+          "type": "readonly LumenChartSeries[]"
+        },
+        {
+          "name": "showLegend",
+          "optional": true,
+          "type": "boolean"
+        },
+        {
+          "name": "showTable",
+          "optional": true,
+          "type": "boolean"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'figure'>",
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
+        }
+      ],
+      "runtimeEvents": []
+    },
     {
       "apiReference": [
         {
@@ -3533,8 +3868,20 @@
         {
           "attribute": "children",
           "defaultValue": "required",
-          "description": "Composes the chart presentation while the consumer owns the visualization data and accessible description.",
-          "values": "header, SVG or canvas, and optional caption"
+          "description": "Composes a specialized visualization while the consumer owns its data and accessible description.",
+          "values": "custom SVG, canvas, HTML plot, and optional table"
+        },
+        {
+          "attribute": "heading, description, value",
+          "defaultValue": "-",
+          "description": "Builds the standard visible chart header without consuming the native title attribute.",
+          "values": "string"
+        },
+        {
+          "attribute": "caption",
+          "defaultValue": "-",
+          "description": "Adds a semantic figcaption after the custom plot.",
+          "values": "string"
         },
         {
           "attribute": "class, className",
@@ -3549,9 +3896,11 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  class?: string | null\n  className?: string\n  glass?: boolean | 'subtle' | 'strong'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  glass = false,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-chart',\n    glass && 'ui-chart--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<figure\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</figure>\n",
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  caption?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  value?: string\n}\n\nconst {\n  caption,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  value,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-chart',\n    glass && 'ui-chart--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<figure\n  class:list={classList}\n  {...passthrough}\n>\n  {\n    (heading || description || value || Astro.slots.has('header')) && (\n      <header>\n        <slot name=\"header\">\n          <div class=\"ui-chart__heading\">\n            {heading && <h3>{heading}</h3>}\n            {description && <p>{description}</p>}\n          </div>\n          {value && <strong data-ui-chart-value>{value}</strong>}\n        </slot>\n        <slot name=\"actions\" />\n      </header>\n    )\n  }\n  <slot />\n  {caption && <figcaption>{caption}</figcaption>}\n</figure>\n",
       "category": "Data display",
-      "collections": [],
+      "collections": [
+        "Data visualization"
+      ],
       "dependencies": [
         "styles"
       ],
@@ -3569,7 +3918,12 @@
           "packageName": "@santi020k/lumen-astro",
           "props": [
             {
-              "name": "class",
+              "name": "caption",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "class",
               "optional": true,
               "type": "string | null"
             },
@@ -3578,20 +3932,37 @@
               "optional": true,
               "type": "string"
             },
+            {
+              "name": "description",
+              "optional": true,
+              "type": "string"
+            },
             {
               "name": "glass",
               "optional": true,
               "type": "boolean | 'subtle' | 'strong'"
+            },
+            {
+              "name": "heading",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "value",
+              "optional": true,
+              "type": "string"
             }
           ],
           "propsExtends": "HTMLAttributes<'figure'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  class?: string | null\n  className?: string\n  glass?: boolean | 'subtle' | 'strong'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  glass = false,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-chart',\n    glass && 'ui-chart--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<figure\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</figure>\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  caption?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  value?: string\n}\n\nconst {\n  caption,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  value,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-chart',\n    glass && 'ui-chart--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<figure\n  class:list={classList}\n  {...passthrough}\n>\n  {\n    (heading || description || value || Astro.slots.has('header')) && (\n      <header>\n        <slot name=\"header\">\n          <div class=\"ui-chart__heading\">\n            {heading && <h3>{heading}</h3>}\n            {description && <p>{description}</p>}\n          </div>\n          {value && <strong data-ui-chart-value>{value}</strong>}\n        </slot>\n        <slot name=\"actions\" />\n      </header>\n    )\n  }\n  <slot />\n  {caption && <figcaption>{caption}</figcaption>}\n</figure>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
           "attributes": [
             "glass",
             "children",
+            "heading, description, value",
+            "caption",
             "class, className",
             "...native attributes"
           ],
@@ -3618,14 +3989,34 @@
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
           "props": [
+            {
+              "name": "caption",
+              "optional": true,
+              "type": "ReactNode"
+            },
+            {
+              "name": "description",
+              "optional": true,
+              "type": "ReactNode"
+            },
             {
               "name": "glass",
               "optional": true,
               "type": "LumenGlassProp"
+            },
+            {
+              "name": "heading",
+              "optional": true,
+              "type": "ReactNode"
+            },
+            {
+              "name": "value",
+              "optional": true,
+              "type": "ReactNode"
             }
           ],
           "propsExtends": "ComponentPropsWithoutRef<'figure'>",
-          "source": "export interface ChartProps extends ComponentPropsWithoutRef<'figure'> {\n  glass?: LumenGlassProp\n}\n\nexport const Chart = ({ className, glass = false, ...props }: ChartProps) => (\n  <figure className={composeClassName('ui-chart', glassClass('ui-chart', glass), className)} {...props} />\n)",
+          "source": "export interface ChartProps extends ComponentPropsWithoutRef<'figure'> {\n  caption?: ReactNode\n  description?: ReactNode\n  glass?: LumenGlassProp\n  heading?: ReactNode\n  value?: ReactNode\n}\n\nexport const Chart = ({\n  caption,\n  children,\n  className,\n  description,\n  glass = false,\n  heading,\n  value,\n  ...props\n}: ChartProps) => (\n  <figure className={composeClassName('ui-chart', glassClass('ui-chart', glass), className)} {...props}>\n    {(heading || description || value) && (\n      <header>\n        <div className=\"ui-chart__heading\">\n          {heading && <h3>{heading}</h3>}\n          {description && <p>{description}</p>}\n        </div>\n        {value && <strong data-ui-chart-value>{value}</strong>}\n      </header>\n    )}\n    {children}\n    {caption && <figcaption>{caption}</figcaption>}\n  </figure>\n)",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -3639,21 +4030,39 @@
       "keyboardInteractions": [],
       "keywords": [
         "and",
+        "breakdowns",
         "captions",
+        "categorical",
         "chart",
+        "compact",
+        "comparisons",
+        "custom",
         "data",
         "display",
         "for",
         "frames",
         "headers",
         "lightweight",
+        "match",
         "metric",
+        "metrics",
+        "ordered",
+        "part",
         "plots",
+        "question",
         "svg",
-        "visualization"
+        "the",
+        "trends",
+        "visualization",
+        "whole"
       ],
       "name": "Chart",
       "props": [
+        {
+          "name": "caption",
+          "optional": true,
+          "type": "string"
+        },
         {
           "name": "class",
           "optional": true,
@@ -3664,14 +4073,34 @@
           "optional": true,
           "type": "string"
         },
+        {
+          "name": "description",
+          "optional": true,
+          "type": "string"
+        },
         {
           "name": "glass",
           "optional": true,
           "type": "boolean | 'subtle' | 'strong'"
+        },
+        {
+          "name": "heading",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "value",
+          "optional": true,
+          "type": "string"
         }
       ],
       "propsExtends": "HTMLAttributes<'figure'>",
-      "recipes": [],
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
+        }
+      ],
       "runtimeEvents": []
     },
     {
@@ -8338,7 +8767,7 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport {\n  renderLumenIconSvg,\n  resolveLumenAstroProps,\n  type LumenIconName\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype IconSize = 'default' | 'lg' | 'sm' | 'xl'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  decorative?: boolean\n  label?: string\n  name?: LumenIconName\n  size?: IconSize\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  decorative,\n  label,\n  name,\n  size = 'default',\n  ...rest\n} = Astro.props\n\nconst isDecorative = decorative ?? !label\nconst iconSvg = name ? renderLumenIconSvg(name) : ''\n\nif (name && !iconSvg && import.meta.env.DEV) {\n  console.warn(`[Lumen Icon] Unknown Lucide icon \"${name}\". Use the default slot for brand or project-specific SVGs.`)\n}\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-icon',\n  size === 'sm' && 'ui-icon--sm',\n  size === 'lg' && 'ui-icon--lg',\n  size === 'xl' && 'ui-icon--xl'\n], classProp, className)\n---\n\n<span\n  aria-hidden={isDecorative ? 'true' : undefined}\n  aria-label={!isDecorative ? label : undefined}\n  class:list={classList}\n  role={!isDecorative ? 'img' : undefined}\n  {...passthrough}\n>\n  {name ? <Fragment set:html={iconSvg} /> : <slot />}\n</span>\n",
+      "astroSource": "---\nimport {\n  renderLumenIconSvg,\n  resolveLumenAstroProps,\n  type LumenIconName\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype IconSize = 'default' | 'lg' | 'sm' | 'xl'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  decorative?: boolean\n  label?: string\n  name?: LumenIconName\n  size?: IconSize\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  decorative,\n  label,\n  name,\n  size = 'default',\n  ...rest\n} = Astro.props\n\nconst isDecorative = decorative ?? !label\nconst iconSvg = name ? renderLumenIconSvg(name) : ''\n\nif (name && !iconSvg && import.meta.env.DEV) {\n  console.warn(`[Lumen Icon] Unknown icon \"${name}\". Register an icon pack or use the default slot for project-specific SVGs.`)\n}\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-icon',\n  size === 'sm' && 'ui-icon--sm',\n  size === 'lg' && 'ui-icon--lg',\n  size === 'xl' && 'ui-icon--xl'\n], classProp, className)\n---\n\n<span\n  aria-hidden={isDecorative ? 'true' : undefined}\n  aria-label={!isDecorative ? label : undefined}\n  class:list={classList}\n  role={!isDecorative ? 'img' : undefined}\n  {...passthrough}\n>\n  {name ? <Fragment set:html={iconSvg} /> : <slot />}\n</span>\n",
       "category": "Data display",
       "collections": [],
       "dependencies": [
@@ -8390,7 +8819,7 @@
             }
           ],
           "propsExtends": "HTMLAttributes<'span'>",
-          "source": "---\nimport {\n  renderLumenIconSvg,\n  resolveLumenAstroProps,\n  type LumenIconName\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype IconSize = 'default' | 'lg' | 'sm' | 'xl'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  decorative?: boolean\n  label?: string\n  name?: LumenIconName\n  size?: IconSize\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  decorative,\n  label,\n  name,\n  size = 'default',\n  ...rest\n} = Astro.props\n\nconst isDecorative = decorative ?? !label\nconst iconSvg = name ? renderLumenIconSvg(name) : ''\n\nif (name && !iconSvg && import.meta.env.DEV) {\n  console.warn(`[Lumen Icon] Unknown Lucide icon \"${name}\". Use the default slot for brand or project-specific SVGs.`)\n}\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-icon',\n  size === 'sm' && 'ui-icon--sm',\n  size === 'lg' && 'ui-icon--lg',\n  size === 'xl' && 'ui-icon--xl'\n], classProp, className)\n---\n\n<span\n  aria-hidden={isDecorative ? 'true' : undefined}\n  aria-label={!isDecorative ? label : undefined}\n  class:list={classList}\n  role={!isDecorative ? 'img' : undefined}\n  {...passthrough}\n>\n  {name ? <Fragment set:html={iconSvg} /> : <slot />}\n</span>\n",
+          "source": "---\nimport {\n  renderLumenIconSvg,\n  resolveLumenAstroProps,\n  type LumenIconName\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype IconSize = 'default' | 'lg' | 'sm' | 'xl'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  decorative?: boolean\n  label?: string\n  name?: LumenIconName\n  size?: IconSize\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  decorative,\n  label,\n  name,\n  size = 'default',\n  ...rest\n} = Astro.props\n\nconst isDecorative = decorative ?? !label\nconst iconSvg = name ? renderLumenIconSvg(name) : ''\n\nif (name && !iconSvg && import.meta.env.DEV) {\n  console.warn(`[Lumen Icon] Unknown icon \"${name}\". Register an icon pack or use the default slot for project-specific SVGs.`)\n}\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-icon',\n  size === 'sm' && 'ui-icon--sm',\n  size === 'lg' && 'ui-icon--lg',\n  size === 'xl' && 'ui-icon--xl'\n], classProp, className)\n---\n\n<span\n  aria-hidden={isDecorative ? 'true' : undefined}\n  aria-label={!isDecorative ? label : undefined}\n  class:list={classList}\n  role={!isDecorative ? 'img' : undefined}\n  {...passthrough}\n>\n  {name ? <Fragment set:html={iconSvg} /> : <slot />}\n</span>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
@@ -9971,10 +10400,46 @@
     {
       "apiReference": [
         {
-          "attribute": "variant",
-          "defaultValue": "\"default\"",
-          "description": "Controls the marker tone.",
-          "values": "\"default\" | \"success\" | \"warning\" | \"danger\""
+          "attribute": "glass",
+          "defaultValue": "false",
+          "description": "Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; \"subtle\" and \"strong\" adjust the fill intensity.",
+          "values": "boolean | \"subtle\" | \"strong\""
+        },
+        {
+          "attribute": "series",
+          "defaultValue": "required",
+          "description": "Provides ordered, already-aggregated points; null y values create visible gaps.",
+          "values": "LumenChartSeries[]"
+        },
+        {
+          "attribute": "area",
+          "defaultValue": "false",
+          "description": "Adds a tokenized fill between each line segment and the zero or domain baseline.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "markers",
+          "defaultValue": "true",
+          "description": "Shows point markers as a second visual cue and exposes per-point SVG titles.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "referenceValue",
+          "defaultValue": "-",
+          "description": "Draws a dashed threshold or comparison line across the plot.",
+          "values": "number"
+        },
+        {
+          "attribute": "showLegend",
+          "defaultValue": "true for multiple series",
+          "description": "Shows the color-independent series key.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "showTable",
+          "defaultValue": "true",
+          "description": "Provides a revealable semantic table containing every plotted value.",
+          "values": "boolean"
         },
         {
           "attribute": "class, className",
@@ -9989,25 +10454,39 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  variant?: 'default' | 'success' | 'warning' | 'danger'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  variant = 'default',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-marker',\n    variant === 'success' && 'ui-marker--success',\n    variant === 'warning' && 'ui-marker--warning',\n    variant === 'danger' && 'ui-marker--danger'\n], classProp, className)\n---\n\n<span\n  data-variant={variant}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</span>\n",
+      "astroSource": "---\nimport {\n  alignLumenChartSeries,\n  createLumenLineGeometry,\n  getLumenChartCategories,\n  getLumenChartDomain,\n  getLumenChartTicks,\n  hasLumenChartData,\n  type LumenChartSeries,\n  resolveLumenChartTone,\n  scaleLumenChartValue\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\nimport Chart from './Chart.astro'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  area?: boolean\n  caption?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  markers?: boolean\n  referenceValue?: number\n  series: readonly LumenChartSeries[]\n  showLegend?: boolean\n  showTable?: boolean\n}\n\nconst {\n  area = false,\n  caption,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  markers = true,\n  referenceValue,\n  series,\n  showLegend = series.length > 1,\n  showTable = true,\n  ...rest\n} = Astro.props\nconst width = 640\nconst height = 320\nconst padding = 44\nconst categories = getLumenChartCategories(series)\nconst hasData = hasLumenChartData(series)\nconst alignedSeries = series.map(item => alignLumenChartSeries(item, categories))\nconst domain = getLumenChartDomain([\n  ...alignedSeries.flatMap(item => item.data.map(datum => datum.y)),\n  referenceValue ?? null\n], false)\nconst geometries = alignedSeries.map(item =>\n  createLumenLineGeometry(item.data, {\n    domain,\n    height,\n    includeZero: false,\n    padding,\n    width\n  })\n)\nconst ticks = getLumenChartTicks(domain)\nconst labelStep = Math.max(1, Math.ceil(categories.length / 8))\nconst valueFor = (item: LumenChartSeries, category: number | string) =>\n  item.data.find(datum => datum.x === category)\nconst referenceY =\n  referenceValue === undefined\n    ? undefined\n    : scaleLumenChartValue(referenceValue, domain, height - padding, padding)\n---\n\n<Chart\n  class:list={['ui-line-chart', classProp, className]}\n  {caption}\n  {description}\n  {glass}\n  {heading}\n  {...rest}\n>\n  {\n    showLegend && hasData && (\n      <ul class=\"ui-chart__legend\" aria-label=\"Chart legend\">\n        {series.map((item, index) => (\n          <li class={`ui-chart-tone--${resolveLumenChartTone(item.tone, index)}`}>\n            <span aria-hidden=\"true\" />\n            {item.label}\n          </li>\n        ))}\n      </ul>\n    )\n  }\n  {!hasData && <p class=\"ui-chart__empty\" role=\"status\">No chart data available.</p>}\n  <div class=\"ui-chart__plot\" hidden={!hasData}>\n    <svg\n      aria-hidden=\"true\"\n      preserveAspectRatio=\"xMidYMid meet\"\n      viewBox={`0 0 ${width} ${height}`}\n    >\n      <g class=\"ui-chart__grid\">\n        {\n          ticks.map((tick) => {\n            const y = scaleLumenChartValue(\n              tick,\n              domain,\n              height - padding,\n              padding\n            )\n\n            return (\n              <>\n                <line x1={padding} x2={width - padding} y1={y} y2={y} />\n                <text x={padding - 8} y={y}>\n                  {Number(tick.toPrecision(4))}\n                </text>\n              </>\n            )\n          })\n        }\n      </g>\n      <g class=\"ui-chart__axis-labels\">\n        {\n          categories.map((category, index) => {\n            if (\n              index % labelStep !== 0 &&\n              index !== categories.length - 1\n            )\n              return null\n\n            const denominator = Math.max(1, categories.length - 1)\n            const x =\n              padding + (index / denominator) * (width - padding * 2)\n\n            return (\n              <text text-anchor=\"middle\" x={x} y={height - 14}>\n                {String(category)}\n              </text>\n            )\n          })\n        }\n      </g>\n      {\n        referenceY !== undefined && (\n          <line\n            class=\"ui-chart__reference\"\n            x1={padding}\n            x2={width - padding}\n            y1={referenceY}\n            y2={referenceY}\n          />\n        )\n      }\n      {\n        geometries.map((geometry, index) => {\n          const item = series[index]\n\n          if (!item) return null\n\n          const tone = resolveLumenChartTone(item.tone, index)\n\n          return (\n            <g class={`ui-line-chart__series ui-chart-tone--${tone}`}>\n              {area &&\n                geometry.areaPaths.map(path => (\n                  <path class=\"ui-line-chart__area\" d={path} />\n                ))}\n              <path class=\"ui-line-chart__line\" d={geometry.path} />\n              {markers &&\n                geometry.points.map(point => (\n                  <circle\n                    class=\"ui-line-chart__point\"\n                    cx={point.xCoordinate}\n                    cy={point.yCoordinate}\n                    r=\"3\"\n                  >\n                    <title>\n                      {`${point.label ?? String(point.x)} · ${item.label}: ${point.y}`}\n                    </title>\n                  </circle>\n                ))}\n            </g>\n          )\n        })\n      }\n    </svg>\n  </div>\n  {\n    showTable && hasData && (\n      <details class=\"ui-chart__data\">\n        <summary>View chart data</summary>\n        <div>\n          <table>\n            <thead>\n              <tr>\n                <th scope=\"col\">Category</th>\n                {series.map(item => <th scope=\"col\">{item.label}</th>)}\n              </tr>\n            </thead>\n            <tbody>\n              {categories.map(category => (\n                <tr>\n                  <th scope=\"row\">{String(category)}</th>\n                  {series.map(item => {\n                    const datum = valueFor(item, category)\n\n                    return (\n                      <td>\n                        {datum?.label ??\n                          (datum?.y === null || datum === undefined\n                            ? 'Not available'\n                            : String(datum.y))}\n                      </td>\n                    )\n                  })}\n                </tr>\n              ))}\n            </tbody>\n          </table>\n        </div>\n      </details>\n    )\n  }\n</Chart>\n",
       "category": "Data display",
-      "collections": [],
+      "collections": [
+        "Data visualization"
+      ],
       "dependencies": [
+        "Chart",
         "styles"
       ],
-      "description": "Highlights status, position, or annotations.",
+      "description": "Shows ordered trends, multiple series, missing-value gaps, areas, markers, and reference values.",
       "files": [
-        "packages/astro/components/Marker.astro",
+        "packages/astro/components/LineChart.astro",
+        "packages/astro/components/Chart.astro",
         "packages/astro/styles/lumen.css"
       ],
       "frameworkDetails": {
         "astro": {
           "available": true,
-          "example": "<Marker variant=\"success\">Live</Marker>",
-          "importStatement": "import { Marker } from '@santi020k/lumen-astro'",
+          "example": "<LineChart aria-label=\"Website traffic\" heading=\"Page views and visits\" series={[{ id: \"views\", label: \"Page views\", data: [{ x: \"Mon\", y: 120 }, { x: \"Tue\", y: 168 }] }, { id: \"visits\", label: \"Visits\", data: [{ x: \"Mon\", y: 82 }, { x: \"Tue\", y: 104 }] }]} />",
+          "importStatement": "import { LineChart } from '@santi020k/lumen-astro'",
           "language": "astro",
           "packageName": "@santi020k/lumen-astro",
           "props": [
+            {
+              "name": "area",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "caption",
+              "optional": true,
+              "type": "string"
+            },
             {
               "name": "class",
               "optional": true,
@@ -10019,18 +10498,59 @@
               "type": "string"
             },
             {
-              "name": "variant",
+              "name": "description",
               "optional": true,
-              "type": "'default' | 'success' | 'warning' | 'danger'"
+              "type": "string"
+            },
+            {
+              "name": "glass",
+              "optional": true,
+              "type": "boolean | 'subtle' | 'strong'"
+            },
+            {
+              "name": "heading",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "markers",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "referenceValue",
+              "optional": true,
+              "type": "number"
+            },
+            {
+              "name": "series",
+              "optional": false,
+              "type": "readonly LumenChartSeries[]"
+            },
+            {
+              "name": "showLegend",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "showTable",
+              "optional": true,
+              "type": "boolean"
             }
           ],
-          "propsExtends": "HTMLAttributes<'span'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  variant?: 'default' | 'success' | 'warning' | 'danger'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  variant = 'default',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-marker',\n    variant === 'success' && 'ui-marker--success',\n    variant === 'warning' && 'ui-marker--warning',\n    variant === 'danger' && 'ui-marker--danger'\n], classProp, className)\n---\n\n<span\n  data-variant={variant}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</span>\n",
+          "propsExtends": "HTMLAttributes<'figure'>",
+          "source": "---\nimport {\n  alignLumenChartSeries,\n  createLumenLineGeometry,\n  getLumenChartCategories,\n  getLumenChartDomain,\n  getLumenChartTicks,\n  hasLumenChartData,\n  type LumenChartSeries,\n  resolveLumenChartTone,\n  scaleLumenChartValue\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\nimport Chart from './Chart.astro'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  area?: boolean\n  caption?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  markers?: boolean\n  referenceValue?: number\n  series: readonly LumenChartSeries[]\n  showLegend?: boolean\n  showTable?: boolean\n}\n\nconst {\n  area = false,\n  caption,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  markers = true,\n  referenceValue,\n  series,\n  showLegend = series.length > 1,\n  showTable = true,\n  ...rest\n} = Astro.props\nconst width = 640\nconst height = 320\nconst padding = 44\nconst categories = getLumenChartCategories(series)\nconst hasData = hasLumenChartData(series)\nconst alignedSeries = series.map(item => alignLumenChartSeries(item, categories))\nconst domain = getLumenChartDomain([\n  ...alignedSeries.flatMap(item => item.data.map(datum => datum.y)),\n  referenceValue ?? null\n], false)\nconst geometries = alignedSeries.map(item =>\n  createLumenLineGeometry(item.data, {\n    domain,\n    height,\n    includeZero: false,\n    padding,\n    width\n  })\n)\nconst ticks = getLumenChartTicks(domain)\nconst labelStep = Math.max(1, Math.ceil(categories.length / 8))\nconst valueFor = (item: LumenChartSeries, category: number | string) =>\n  item.data.find(datum => datum.x === category)\nconst referenceY =\n  referenceValue === undefined\n    ? undefined\n    : scaleLumenChartValue(referenceValue, domain, height - padding, padding)\n---\n\n<Chart\n  class:list={['ui-line-chart', classProp, className]}\n  {caption}\n  {description}\n  {glass}\n  {heading}\n  {...rest}\n>\n  {\n    showLegend && hasData && (\n      <ul class=\"ui-chart__legend\" aria-label=\"Chart legend\">\n        {series.map((item, index) => (\n          <li class={`ui-chart-tone--${resolveLumenChartTone(item.tone, index)}`}>\n            <span aria-hidden=\"true\" />\n            {item.label}\n          </li>\n        ))}\n      </ul>\n    )\n  }\n  {!hasData && <p class=\"ui-chart__empty\" role=\"status\">No chart data available.</p>}\n  <div class=\"ui-chart__plot\" hidden={!hasData}>\n    <svg\n      aria-hidden=\"true\"\n      preserveAspectRatio=\"xMidYMid meet\"\n      viewBox={`0 0 ${width} ${height}`}\n    >\n      <g class=\"ui-chart__grid\">\n        {\n          ticks.map((tick) => {\n            const y = scaleLumenChartValue(\n              tick,\n              domain,\n              height - padding,\n              padding\n            )\n\n            return (\n              <>\n                <line x1={padding} x2={width - padding} y1={y} y2={y} />\n                <text x={padding - 8} y={y}>\n                  {Number(tick.toPrecision(4))}\n                </text>\n              </>\n            )\n          })\n        }\n      </g>\n      <g class=\"ui-chart__axis-labels\">\n        {\n          categories.map((category, index) => {\n            if (\n              index % labelStep !== 0 &&\n              index !== categories.length - 1\n            )\n              return null\n\n            const denominator = Math.max(1, categories.length - 1)\n            const x =\n              padding + (index / denominator) * (width - padding * 2)\n\n            return (\n              <text text-anchor=\"middle\" x={x} y={height - 14}>\n                {String(category)}\n              </text>\n            )\n          })\n        }\n      </g>\n      {\n        referenceY !== undefined && (\n          <line\n            class=\"ui-chart__reference\"\n            x1={padding}\n            x2={width - padding}\n            y1={referenceY}\n            y2={referenceY}\n          />\n        )\n      }\n      {\n        geometries.map((geometry, index) => {\n          const item = series[index]\n\n          if (!item) return null\n\n          const tone = resolveLumenChartTone(item.tone, index)\n\n          return (\n            <g class={`ui-line-chart__series ui-chart-tone--${tone}`}>\n              {area &&\n                geometry.areaPaths.map(path => (\n                  <path class=\"ui-line-chart__area\" d={path} />\n                ))}\n              <path class=\"ui-line-chart__line\" d={geometry.path} />\n              {markers &&\n                geometry.points.map(point => (\n                  <circle\n                    class=\"ui-line-chart__point\"\n                    cx={point.xCoordinate}\n                    cy={point.yCoordinate}\n                    r=\"3\"\n                  >\n                    <title>\n                      {`${point.label ?? String(point.x)} · ${item.label}: ${point.y}`}\n                    </title>\n                  </circle>\n                ))}\n            </g>\n          )\n        })\n      }\n    </svg>\n  </div>\n  {\n    showTable && hasData && (\n      <details class=\"ui-chart__data\">\n        <summary>View chart data</summary>\n        <div>\n          <table>\n            <thead>\n              <tr>\n                <th scope=\"col\">Category</th>\n                {series.map(item => <th scope=\"col\">{item.label}</th>)}\n              </tr>\n            </thead>\n            <tbody>\n              {categories.map(category => (\n                <tr>\n                  <th scope=\"row\">{String(category)}</th>\n                  {series.map(item => {\n                    const datum = valueFor(item, category)\n\n                    return (\n                      <td>\n                        {datum?.label ??\n                          (datum?.y === null || datum === undefined\n                            ? 'Not available'\n                            : String(datum.y))}\n                      </td>\n                    )\n                  })}\n                </tr>\n              ))}\n            </tbody>\n          </table>\n        </div>\n      </details>\n    )\n  }\n</Chart>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
           "attributes": [
-            "variant",
+            "glass",
+            "series",
+            "area",
+            "markers",
+            "referenceValue",
+            "showLegend",
+            "showTable",
             "class, className",
             "...native attributes"
           ],
@@ -10039,32 +10559,57 @@
             "mode": "registration",
             "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
           },
-          "example": "<lumen-marker variant=\"success\">Live</lumen-marker>",
+          "example": "<lumen-line-chart></lumen-line-chart>",
           "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
           "language": "html",
           "packageName": "@santi020k/lumen-elements",
           "props": [],
           "propsExtends": "HTMLElement attributes",
           "registration": "defineLumenElements()",
-          "source": "Marker: {\n    attributeClasses: {\n      variant: {\n        danger: 'ui-marker--danger',\n        success: 'ui-marker--success',\n        warning: 'ui-marker--warning'\n      }\n    },\n    baseClassName: 'ui-marker',\n    defaults: { variant: 'default' },\n    tagName: 'lumen-marker'\n  }",
+          "source": "LineChart: {\n    attributeClasses: glassAttributeClasses('ui-chart--glass'),\n    baseClassName: 'ui-chart ui-line-chart',\n    role: 'figure',\n    tagName: 'lumen-line-chart'\n  }",
           "styleImport": "import '@santi020k/lumen-elements/styles.css'",
-          "tagName": "lumen-marker"
+          "tagName": "lumen-line-chart"
         },
         "react": {
           "available": true,
-          "example": "<Marker variant=\"success\">Live</Marker>",
-          "importStatement": "import { Marker } from '@santi020k/lumen-react'",
+          "example": "<LineChart aria-label=\"Website traffic\" heading=\"Page views and visits\" series={[{ id: \"views\", label: \"Page views\", data: [{ x: \"Mon\", y: 120 }, { x: \"Tue\", y: 168 }] }, { id: \"visits\", label: \"Visits\", data: [{ x: \"Mon\", y: 82 }, { x: \"Tue\", y: 104 }] }]} />",
+          "importStatement": "import { LineChart } from '@santi020k/lumen-react'",
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
           "props": [
             {
-              "name": "variant",
+              "name": "area",
               "optional": true,
-              "type": "MarkerVariant"
+              "type": "boolean"
+            },
+            {
+              "name": "markers",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "referenceValue",
+              "optional": true,
+              "type": "number"
+            },
+            {
+              "name": "series",
+              "optional": true,
+              "type": "readonly LumenChartSeries[]"
+            },
+            {
+              "name": "showLegend",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "showTable",
+              "optional": true,
+              "type": "boolean"
             }
           ],
-          "propsExtends": "ComponentPropsWithoutRef<'span'>",
-          "source": "export interface MarkerProps extends ComponentPropsWithoutRef<'span'> {\n  variant?: MarkerVariant\n}\n\nexport const Marker = ({ className, variant = 'default', ...props }: MarkerProps) => (\n  <span\n    className={composeClassName('ui-marker', variantClass('ui-marker', variant), className)}\n    data-variant={variant}\n    {...props}\n  />\n)",
+          "propsExtends": "Omit<ChartProps, 'children'>",
+          "source": "export interface LineChartProps extends Omit<ChartProps, 'children'> {\n  area?: boolean\n  markers?: boolean\n  referenceValue?: number\n  series?: readonly LumenChartSeries[]\n  showLegend?: boolean\n  showTable?: boolean\n}\n\nexport const LineChart = ({\n  area = false,\n  className,\n  markers = true,\n  referenceValue,\n  series = emptyChartSeries,\n  showLegend = series.length > 1,\n  showTable = true,\n  ...props\n}: LineChartProps) => {\n  const width = 640\n  const height = 320\n  const padding = 44\n  const categories = getLumenChartCategories(series)\n  const hasData = hasLumenChartData(series)\n  const alignedSeries = series.map(item => alignLumenChartSeries(item, categories))\n\n  const domain = getLumenChartDomain([\n    ...alignedSeries.flatMap(item => item.data.map(datum => datum.y)),\n    referenceValue ?? null\n  ], false)\n\n  const geometries = alignedSeries.map(item =>\n    createLumenLineGeometry(item.data, {\n      domain,\n      height,\n      includeZero: false,\n      padding,\n      width\n    })\n  )\n\n  const ticks = getLumenChartTicks(domain)\n  const labelStep = Math.max(1, Math.ceil(categories.length / 8))\n\n  const referenceY = referenceValue === undefined\n    ? undefined\n    : scaleLumenChartValue(referenceValue, domain, height - padding, padding)\n\n  return (\n    <Chart className={composeClassName('ui-line-chart', className)} {...props}>\n      {showLegend && hasData && <ChartLegend series={series} />}\n      {!hasData && (\n        <p className=\"ui-chart__empty\" role=\"status\">No chart data available.</p>\n      )}\n      <div className=\"ui-chart__plot\" hidden={!hasData}>\n        <svg\n          aria-hidden=\"true\"\n          preserveAspectRatio=\"xMidYMid meet\"\n          viewBox={`0 0 ${width} ${height}`}\n        >\n          <g className=\"ui-chart__grid\">\n            {ticks.map(tick => {\n              const y = scaleLumenChartValue(tick, domain, height - padding, padding)\n\n              return (\n                <Fragment key={tick}>\n                  <line x1={padding} x2={width - padding} y1={y} y2={y} />\n                  <text x={padding - 8} y={y}>{Number(tick.toPrecision(4))}</text>\n                </Fragment>\n              )\n            })}\n          </g>\n          <g className=\"ui-chart__axis-labels\">\n            {categories.map((category, index) => {\n              if (index % labelStep !== 0 && index !== categories.length - 1) return null\n\n              const denominator = Math.max(1, categories.length - 1)\n              const x = padding + (index / denominator) * (width - padding * 2)\n\n              return (\n                <text\n                  key={`${typeof category}:${String(category)}`}\n                  textAnchor=\"middle\"\n                  x={x}\n                  y={height - 14}\n                >\n                  {String(category)}\n                </text>\n              )\n            })}\n          </g>\n          {referenceY !== undefined && (\n            <line\n              className=\"ui-chart__reference\"\n              x1={padding}\n              x2={width - padding}\n              y1={referenceY}\n              y2={referenceY}\n            />\n          )}\n          {geometries.map((geometry, index) => {\n            const item = series[index]\n\n            if (!item) return null\n\n            const tone = resolveLumenChartTone(item.tone, index)\n\n            return (\n              <g\n                className={`ui-line-chart__series ui-chart-tone--${tone}`}\n                key={item.id}\n              >\n                {area && geometry.areaPaths.map(path => (\n                  <path className=\"ui-line-chart__area\" d={path} key={path} />\n                ))}\n                <path className=\"ui-line-chart__line\" d={geometry.path} />\n                {markers && geometry.points.map(point => (\n                  <circle\n                    className=\"ui-line-chart__point\"\n                    cx={point.xCoordinate}\n                    cy={point.yCoordinate}\n                    key={`${typeof point.x}:${String(point.x)}`}\n                    r=\"3\"\n                  >\n                    <title>\n                      {`${point.label ?? String(point.x)} · ${item.label}: ${String(point.y)}`}\n                    </title>\n                  </circle>\n                ))}\n              </g>\n            )\n          })}\n        </svg>\n      </div>\n      {showTable && hasData && (\n        <ChartDataTable categories={categories} series={series} />\n      )}\n    </Chart>\n  )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -10074,43 +10619,71 @@
         "react": true
       },
       "guidance": {
-        "when": "Use for compact operational status where a colored dot should carry the visual signal.",
-        "distinction": "Use Badge for a filled metadata label and Pill for a label paired with a count."
+        "when": "Use to show how one or more ordered series change, including missing values and thresholds.",
+        "distinction": "Use BarChart for categorical magnitude comparisons and Sparkline when axes and exact values are unnecessary."
       },
-      "kebab": "marker",
+      "kebab": "line-chart",
       "keyboardInteractions": [],
       "keywords": [
         "and",
-        "annotations",
-        "badge",
-        "carry",
-        "colored",
+        "are",
+        "areas",
+        "axes",
+        "barchart",
+        "breakdowns",
+        "categorical",
+        "change",
         "compact",
-        "count",
+        "comparisons",
+        "custom",
         "data",
         "display",
-        "dot",
-        "filled",
+        "exact",
         "for",
-        "highlights",
-        "label",
-        "marker",
-        "metadata",
-        "operational",
-        "paired",
-        "pill",
-        "position",
-        "should",
-        "signal",
-        "status",
+        "gaps",
+        "how",
+        "including",
+        "linechart",
+        "magnitude",
+        "markers",
+        "match",
+        "metrics",
+        "missing",
+        "more",
+        "multiple",
+        "one",
+        "ordered",
+        "part",
+        "plots",
+        "question",
+        "reference",
+        "series",
+        "show",
+        "shows",
+        "sparkline",
         "the",
+        "thresholds",
+        "trends",
+        "unnecessary",
         "use",
-        "visual",
-        "where",
-        "with"
+        "value",
+        "values",
+        "visualization",
+        "when",
+        "whole"
       ],
-      "name": "Marker",
+      "name": "LineChart",
       "props": [
+        {
+          "name": "area",
+          "optional": true,
+          "type": "boolean"
+        },
+        {
+          "name": "caption",
+          "optional": true,
+          "type": "string"
+        },
         {
           "name": "class",
           "optional": true,
@@ -10122,37 +10695,240 @@
           "type": "string"
         },
         {
-          "name": "variant",
+          "name": "description",
           "optional": true,
-          "type": "'default' | 'success' | 'warning' | 'danger'"
-        }
-      ],
-      "propsExtends": "HTMLAttributes<'span'>",
-      "recipes": [],
-      "runtimeEvents": []
-    },
-    {
-      "apiReference": [
-        {
-          "attribute": "glass",
-          "defaultValue": "false",
-          "description": "Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; \"subtle\" and \"strong\" adjust the fill intensity.",
-          "values": "boolean | \"subtle\" | \"strong\""
+          "type": "string"
         },
         {
-          "attribute": "surface",
-          "defaultValue": "\"default\"",
-          "description": "Deprecated alias for glass; surface=\"glass\" maps to glass={true}.",
-          "values": "\"default\" | \"glass\""
+          "name": "glass",
+          "optional": true,
+          "type": "boolean | 'subtle' | 'strong'"
         },
         {
-          "attribute": "class, className",
-          "defaultValue": "\"\"",
-          "description": "Merges custom classes with the generated ui-* root classes.",
-          "values": "string"
+          "name": "heading",
+          "optional": true,
+          "type": "string"
         },
         {
-          "attribute": "...native attributes",
+          "name": "markers",
+          "optional": true,
+          "type": "boolean"
+        },
+        {
+          "name": "referenceValue",
+          "optional": true,
+          "type": "number"
+        },
+        {
+          "name": "series",
+          "optional": false,
+          "type": "readonly LumenChartSeries[]"
+        },
+        {
+          "name": "showLegend",
+          "optional": true,
+          "type": "boolean"
+        },
+        {
+          "name": "showTable",
+          "optional": true,
+          "type": "boolean"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'figure'>",
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
+        }
+      ],
+      "runtimeEvents": []
+    },
+    {
+      "apiReference": [
+        {
+          "attribute": "variant",
+          "defaultValue": "\"default\"",
+          "description": "Controls the marker tone.",
+          "values": "\"default\" | \"success\" | \"warning\" | \"danger\""
+        },
+        {
+          "attribute": "class, className",
+          "defaultValue": "\"\"",
+          "description": "Merges custom classes with the generated ui-* root classes.",
+          "values": "string"
+        },
+        {
+          "attribute": "...native attributes",
+          "defaultValue": "-",
+          "description": "Forwards standard attributes to the root element unless the component consumes them.",
+          "values": "HTML attributes"
+        }
+      ],
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  variant?: 'default' | 'success' | 'warning' | 'danger'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  variant = 'default',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-marker',\n    variant === 'success' && 'ui-marker--success',\n    variant === 'warning' && 'ui-marker--warning',\n    variant === 'danger' && 'ui-marker--danger'\n], classProp, className)\n---\n\n<span\n  data-variant={variant}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</span>\n",
+      "category": "Data display",
+      "collections": [],
+      "dependencies": [
+        "styles"
+      ],
+      "description": "Highlights status, position, or annotations.",
+      "files": [
+        "packages/astro/components/Marker.astro",
+        "packages/astro/styles/lumen.css"
+      ],
+      "frameworkDetails": {
+        "astro": {
+          "available": true,
+          "example": "<Marker variant=\"success\">Live</Marker>",
+          "importStatement": "import { Marker } from '@santi020k/lumen-astro'",
+          "language": "astro",
+          "packageName": "@santi020k/lumen-astro",
+          "props": [
+            {
+              "name": "class",
+              "optional": true,
+              "type": "string | null"
+            },
+            {
+              "name": "className",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "'default' | 'success' | 'warning' | 'danger'"
+            }
+          ],
+          "propsExtends": "HTMLAttributes<'span'>",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  variant?: 'default' | 'success' | 'warning' | 'danger'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  variant = 'default',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-marker',\n    variant === 'success' && 'ui-marker--success',\n    variant === 'warning' && 'ui-marker--warning',\n    variant === 'danger' && 'ui-marker--danger'\n], classProp, className)\n---\n\n<span\n  data-variant={variant}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</span>\n",
+          "styleImport": "import '@santi020k/lumen-astro/styles.css'"
+        },
+        "elements": {
+          "attributes": [
+            "variant",
+            "class, className",
+            "...native attributes"
+          ],
+          "available": true,
+          "behavior": {
+            "mode": "registration",
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
+          },
+          "example": "<lumen-marker variant=\"success\">Live</lumen-marker>",
+          "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
+          "language": "html",
+          "packageName": "@santi020k/lumen-elements",
+          "props": [],
+          "propsExtends": "HTMLElement attributes",
+          "registration": "defineLumenElements()",
+          "source": "Marker: {\n    attributeClasses: {\n      variant: {\n        danger: 'ui-marker--danger',\n        success: 'ui-marker--success',\n        warning: 'ui-marker--warning'\n      }\n    },\n    baseClassName: 'ui-marker',\n    defaults: { variant: 'default' },\n    tagName: 'lumen-marker'\n  }",
+          "styleImport": "import '@santi020k/lumen-elements/styles.css'",
+          "tagName": "lumen-marker"
+        },
+        "react": {
+          "available": true,
+          "example": "<Marker variant=\"success\">Live</Marker>",
+          "importStatement": "import { Marker } from '@santi020k/lumen-react'",
+          "language": "tsx",
+          "packageName": "@santi020k/lumen-react",
+          "props": [
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "MarkerVariant"
+            }
+          ],
+          "propsExtends": "ComponentPropsWithoutRef<'span'>",
+          "source": "export interface MarkerProps extends ComponentPropsWithoutRef<'span'> {\n  variant?: MarkerVariant\n}\n\nexport const Marker = ({ className, variant = 'default', ...props }: MarkerProps) => (\n  <span\n    className={composeClassName('ui-marker', variantClass('ui-marker', variant), className)}\n    data-variant={variant}\n    {...props}\n  />\n)",
+          "styleImport": "import '@santi020k/lumen-react/styles.css'"
+        }
+      },
+      "frameworks": {
+        "astro": true,
+        "elements": true,
+        "react": true
+      },
+      "guidance": {
+        "when": "Use for compact operational status where a colored dot should carry the visual signal.",
+        "distinction": "Use Badge for a filled metadata label and Pill for a label paired with a count."
+      },
+      "kebab": "marker",
+      "keyboardInteractions": [],
+      "keywords": [
+        "and",
+        "annotations",
+        "badge",
+        "carry",
+        "colored",
+        "compact",
+        "count",
+        "data",
+        "display",
+        "dot",
+        "filled",
+        "for",
+        "highlights",
+        "label",
+        "marker",
+        "metadata",
+        "operational",
+        "paired",
+        "pill",
+        "position",
+        "should",
+        "signal",
+        "status",
+        "the",
+        "use",
+        "visual",
+        "where",
+        "with"
+      ],
+      "name": "Marker",
+      "props": [
+        {
+          "name": "class",
+          "optional": true,
+          "type": "string | null"
+        },
+        {
+          "name": "className",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "variant",
+          "optional": true,
+          "type": "'default' | 'success' | 'warning' | 'danger'"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'span'>",
+      "recipes": [],
+      "runtimeEvents": []
+    },
+    {
+      "apiReference": [
+        {
+          "attribute": "glass",
+          "defaultValue": "false",
+          "description": "Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; \"subtle\" and \"strong\" adjust the fill intensity.",
+          "values": "boolean | \"subtle\" | \"strong\""
+        },
+        {
+          "attribute": "surface",
+          "defaultValue": "\"default\"",
+          "description": "Deprecated alias for glass; surface=\"glass\" maps to glass={true}.",
+          "values": "\"default\" | \"glass\""
+        },
+        {
+          "attribute": "class, className",
+          "defaultValue": "\"\"",
+          "description": "Merges custom classes with the generated ui-* root classes.",
+          "values": "string"
+        },
+        {
+          "attribute": "...native attributes",
           "defaultValue": "-",
           "description": "Forwards standard attributes to the root element unless the component consumes them.",
           "values": "HTML attributes"
@@ -11519,23 +12295,340 @@
               "type": "string"
             },
             {
-              "name": "name",
+              "name": "name",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "placeholder",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "size",
+              "optional": true,
+              "type": "'default' | 'lg' | 'sm'"
+            }
+          ],
+          "propsExtends": "Omit<ComponentPropsWithoutRef<'div'>, 'defaultValue'>",
+          "source": "export interface PhoneInputProps extends Omit<ComponentPropsWithoutRef<'div'>, 'defaultValue'> {\n  countries?: SelectOption[]\n  countryLabel?: string\n  countryName?: string\n  defaultCountryValue?: string\n  defaultValue?: string\n  name?: string\n  placeholder?: string\n  size?: 'default' | 'lg' | 'sm'\n}\n\nexport const PhoneInput = ({\n  className,\n  countries = emptyOptions,\n  countryLabel = 'Country code',\n  countryName = 'country',\n  defaultCountryValue,\n  defaultValue,\n  name = 'phone',\n  placeholder = 'Phone number',\n  size = 'default',\n  ...props\n}: PhoneInputProps) => {\n  const { selectClass, inputClass } = phoneInputSizeModifiers(size)\n\n  return (\n    <div className={composeClassName('ui-phone-input ui-input-group', className)} {...props}>\n      <select\n        aria-label={countryLabel}\n        className={composeClassName('ui-select ui-phone-input__country', selectClass)}\n        defaultValue={defaultCountryValue}\n        name={countryName}\n      >\n        {countries.map(normalizeOption).map(option => (\n          <option disabled={option.disabled} key={option.value} value={option.value}>\n            {option.label}\n          </option>\n        ))}\n      </select>\n      <input\n        autoComplete=\"tel\"\n        className={composeClassName('ui-input ui-phone-input__number', inputClass)}\n        defaultValue={defaultValue}\n        inputMode=\"tel\"\n        name={name}\n        placeholder={placeholder}\n        type=\"tel\"\n      />\n    </div>\n  )\n}",
+          "styleImport": "import '@santi020k/lumen-react/styles.css'"
+        }
+      },
+      "frameworks": {
+        "astro": true,
+        "elements": true,
+        "react": true
+      },
+      "guidance": null,
+      "kebab": "phone-input",
+      "keyboardInteractions": [],
+      "keywords": [
+        "built",
+        "choose",
+        "code",
+        "country",
+        "data",
+        "dial",
+        "entry",
+        "field",
+        "forms",
+        "input",
+        "needs",
+        "number",
+        "only",
+        "pairs",
+        "phoneinput",
+        "purpose",
+        "select",
+        "start",
+        "telephone",
+        "text",
+        "the",
+        "then",
+        "when",
+        "with"
+      ],
+      "name": "PhoneInput",
+      "props": [
+        {
+          "name": "class",
+          "optional": true,
+          "type": "string | null"
+        },
+        {
+          "name": "className",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "countries",
+          "optional": true,
+          "type": "Country[]"
+        },
+        {
+          "name": "countryLabel",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "countryName",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "countryValue",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "name",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "placeholder",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "size",
+          "optional": true,
+          "type": "'default' | 'lg' | 'sm'"
+        },
+        {
+          "name": "value",
+          "optional": true,
+          "type": "string"
+        }
+      ],
+      "propsExtends": "Omit<HTMLAttributes<'div'>, 'size'>",
+      "recipes": [],
+      "runtimeEvents": []
+    },
+    {
+      "apiReference": [
+        {
+          "attribute": "glass",
+          "defaultValue": "false",
+          "description": "Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; \"subtle\" and \"strong\" adjust the fill intensity.",
+          "values": "boolean | \"subtle\" | \"strong\""
+        },
+        {
+          "attribute": "series",
+          "defaultValue": "required",
+          "description": "Provides one already-aggregated series whose positive finite data points become slices.",
+          "values": "LumenChartSeries"
+        },
+        {
+          "attribute": "variant",
+          "defaultValue": "\"donut\"",
+          "description": "Uses a center opening by default or renders a traditional pie.",
+          "values": "\"donut\" | \"pie\""
+        },
+        {
+          "attribute": "centerLabel, centerValue",
+          "defaultValue": "-",
+          "description": "Adds optional visual summary content in the donut center.",
+          "values": "string | ReactNode"
+        },
+        {
+          "attribute": "showLegend",
+          "defaultValue": "true",
+          "description": "Shows the color-independent category key.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "showTable",
+          "defaultValue": "true",
+          "description": "Provides a revealable semantic table with category, value, and share columns.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "valueFormatter",
+          "defaultValue": "String",
+          "description": "Formats values in SVG titles and the semantic table for Astro and React; Web Components expose the equivalent JavaScript property.",
+          "values": "(value: number) => string"
+        },
+        {
+          "attribute": "class, className",
+          "defaultValue": "\"\"",
+          "description": "Merges custom classes with the generated ui-* root classes.",
+          "values": "string"
+        },
+        {
+          "attribute": "...native attributes",
+          "defaultValue": "-",
+          "description": "Forwards standard attributes to the root element unless the component consumes them.",
+          "values": "HTML attributes"
+        }
+      ],
+      "astroSource": "---\nimport {\n  createLumenPieGeometry,\n  hasLumenPieData,\n  type LumenChartSeries,\n  type LumenPieChartVariant\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\nimport Chart from './Chart.astro'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  caption?: string\n  centerLabel?: string\n  centerValue?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  series: LumenChartSeries\n  showLegend?: boolean\n  showTable?: boolean\n  valueFormatter?: (value: number) => string\n  variant?: LumenPieChartVariant\n}\n\nconst {\n  caption,\n  centerLabel,\n  centerValue,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  series,\n  showLegend = true,\n  showTable = true,\n  valueFormatter = String,\n  variant = 'donut',\n  ...rest\n} = Astro.props\nconst geometry = createLumenPieGeometry(series.data, { variant })\nconst hasData = hasLumenPieData(series.data)\nconst percentageFor = (percentage: number) =>\n  new Intl.NumberFormat(undefined, {\n    maximumFractionDigits: percentage < 0.01 ? 1 : 0,\n    style: 'percent'\n  }).format(percentage)\n---\n\n<Chart\n  class:list={['ui-pie-chart', `ui-pie-chart--${variant}`, classProp, className]}\n  {caption}\n  {description}\n  {glass}\n  {heading}\n  {...rest}\n>\n  {\n    showLegend && hasData && (\n      <ul class=\"ui-chart__legend\" aria-label=\"Chart legend\">\n        {geometry.slices.map(slice => (\n          <li class={`ui-chart-tone--${slice.tone}`}>\n            <span aria-hidden=\"true\" />\n            {slice.label}\n          </li>\n        ))}\n      </ul>\n    )\n  }\n  {!hasData && <p class=\"ui-chart__empty\" role=\"status\">No chart data available.</p>}\n  <div class=\"ui-chart__plot ui-pie-chart__plot\" hidden={!hasData}>\n    <svg\n      aria-hidden=\"true\"\n      preserveAspectRatio=\"xMidYMid meet\"\n      viewBox={`0 0 ${geometry.size} ${geometry.size}`}\n    >\n      <g class=\"ui-pie-chart__slices\">\n        {\n          geometry.slices.map(slice => (\n            <path\n              class={`ui-chart-tone--${slice.tone}`}\n              d={slice.path}\n              fill-rule=\"evenodd\"\n            >\n              <title>\n                {`${slice.label}: ${valueFormatter(slice.value)} (${percentageFor(slice.percentage)})`}\n              </title>\n            </path>\n          ))\n        }\n      </g>\n    </svg>\n    {\n      variant === 'donut' && (centerLabel != null || centerValue != null) && (\n        <>\n          <div class=\"ui-pie-chart__center\" aria-hidden=\"true\">\n            {centerValue != null && <strong>{centerValue}</strong>}\n            {centerLabel != null && <span>{centerLabel}</span>}\n          </div>\n          <div class=\"ui-sr-only\">\n            {centerValue} {centerLabel}\n          </div>\n        </>\n      )\n    }\n  </div>\n  {\n    showTable && hasData && (\n      <details class=\"ui-chart__data\">\n        <summary>View chart data</summary>\n        <div>\n          <table>\n            <thead>\n              <tr>\n                <th scope=\"col\">Category</th>\n                <th scope=\"col\">Value</th>\n                <th scope=\"col\">Share</th>\n              </tr>\n            </thead>\n            <tbody>\n              {geometry.slices.map(slice => (\n                <tr>\n                  <th scope=\"row\">{slice.label}</th>\n                  <td>{valueFormatter(slice.value)}</td>\n                  <td>{percentageFor(slice.percentage)}</td>\n                </tr>\n              ))}\n            </tbody>\n          </table>\n        </div>\n      </details>\n    )\n  }\n</Chart>\n",
+      "category": "Data display",
+      "collections": [
+        "Data visualization"
+      ],
+      "dependencies": [
+        "Chart",
+        "styles"
+      ],
+      "description": "Shows part-to-whole relationships as an accessible donut or pie chart.",
+      "files": [
+        "packages/astro/components/PieChart.astro",
+        "packages/astro/components/Chart.astro",
+        "packages/astro/styles/lumen.css"
+      ],
+      "frameworkDetails": {
+        "astro": {
+          "available": true,
+          "example": "<PieChart aria-label=\"Framework share\" centerLabel=\"Projects\" centerValue=\"2,480\" heading=\"Framework usage\" series={{ id: \"frameworks\", label: \"Framework share\", data: [{ label: \"Astro\", x: \"astro\", y: 46 }, { label: \"React\", x: \"react\", y: 31 }, { label: \"Web Components\", x: \"elements\", y: 23 }] }} />",
+          "importStatement": "import { PieChart } from '@santi020k/lumen-astro'",
+          "language": "astro",
+          "packageName": "@santi020k/lumen-astro",
+          "props": [
+            {
+              "name": "caption",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "centerLabel",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "centerValue",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "class",
+              "optional": true,
+              "type": "string | null"
+            },
+            {
+              "name": "className",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "description",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "glass",
+              "optional": true,
+              "type": "boolean | 'subtle' | 'strong'"
+            },
+            {
+              "name": "heading",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "series",
+              "optional": false,
+              "type": "LumenChartSeries"
+            },
+            {
+              "name": "showLegend",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "showTable",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "valueFormatter",
+              "optional": true,
+              "type": "(value: number) => string"
+            },
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "LumenPieChartVariant"
+            }
+          ],
+          "propsExtends": "HTMLAttributes<'figure'>",
+          "source": "---\nimport {\n  createLumenPieGeometry,\n  hasLumenPieData,\n  type LumenChartSeries,\n  type LumenPieChartVariant\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\nimport Chart from './Chart.astro'\n\ninterface Props extends HTMLAttributes<'figure'> {\n  caption?: string\n  centerLabel?: string\n  centerValue?: string\n  class?: string | null\n  className?: string\n  description?: string\n  glass?: boolean | 'subtle' | 'strong'\n  heading?: string\n  series: LumenChartSeries\n  showLegend?: boolean\n  showTable?: boolean\n  valueFormatter?: (value: number) => string\n  variant?: LumenPieChartVariant\n}\n\nconst {\n  caption,\n  centerLabel,\n  centerValue,\n  class: classProp = '',\n  className = '',\n  description,\n  glass = false,\n  heading,\n  series,\n  showLegend = true,\n  showTable = true,\n  valueFormatter = String,\n  variant = 'donut',\n  ...rest\n} = Astro.props\nconst geometry = createLumenPieGeometry(series.data, { variant })\nconst hasData = hasLumenPieData(series.data)\nconst percentageFor = (percentage: number) =>\n  new Intl.NumberFormat(undefined, {\n    maximumFractionDigits: percentage < 0.01 ? 1 : 0,\n    style: 'percent'\n  }).format(percentage)\n---\n\n<Chart\n  class:list={['ui-pie-chart', `ui-pie-chart--${variant}`, classProp, className]}\n  {caption}\n  {description}\n  {glass}\n  {heading}\n  {...rest}\n>\n  {\n    showLegend && hasData && (\n      <ul class=\"ui-chart__legend\" aria-label=\"Chart legend\">\n        {geometry.slices.map(slice => (\n          <li class={`ui-chart-tone--${slice.tone}`}>\n            <span aria-hidden=\"true\" />\n            {slice.label}\n          </li>\n        ))}\n      </ul>\n    )\n  }\n  {!hasData && <p class=\"ui-chart__empty\" role=\"status\">No chart data available.</p>}\n  <div class=\"ui-chart__plot ui-pie-chart__plot\" hidden={!hasData}>\n    <svg\n      aria-hidden=\"true\"\n      preserveAspectRatio=\"xMidYMid meet\"\n      viewBox={`0 0 ${geometry.size} ${geometry.size}`}\n    >\n      <g class=\"ui-pie-chart__slices\">\n        {\n          geometry.slices.map(slice => (\n            <path\n              class={`ui-chart-tone--${slice.tone}`}\n              d={slice.path}\n              fill-rule=\"evenodd\"\n            >\n              <title>\n                {`${slice.label}: ${valueFormatter(slice.value)} (${percentageFor(slice.percentage)})`}\n              </title>\n            </path>\n          ))\n        }\n      </g>\n    </svg>\n    {\n      variant === 'donut' && (centerLabel != null || centerValue != null) && (\n        <>\n          <div class=\"ui-pie-chart__center\" aria-hidden=\"true\">\n            {centerValue != null && <strong>{centerValue}</strong>}\n            {centerLabel != null && <span>{centerLabel}</span>}\n          </div>\n          <div class=\"ui-sr-only\">\n            {centerValue} {centerLabel}\n          </div>\n        </>\n      )\n    }\n  </div>\n  {\n    showTable && hasData && (\n      <details class=\"ui-chart__data\">\n        <summary>View chart data</summary>\n        <div>\n          <table>\n            <thead>\n              <tr>\n                <th scope=\"col\">Category</th>\n                <th scope=\"col\">Value</th>\n                <th scope=\"col\">Share</th>\n              </tr>\n            </thead>\n            <tbody>\n              {geometry.slices.map(slice => (\n                <tr>\n                  <th scope=\"row\">{slice.label}</th>\n                  <td>{valueFormatter(slice.value)}</td>\n                  <td>{percentageFor(slice.percentage)}</td>\n                </tr>\n              ))}\n            </tbody>\n          </table>\n        </div>\n      </details>\n    )\n  }\n</Chart>\n",
+          "styleImport": "import '@santi020k/lumen-astro/styles.css'"
+        },
+        "elements": {
+          "attributes": [
+            "variant",
+            "glass",
+            "series",
+            "centerLabel, centerValue",
+            "showLegend",
+            "showTable",
+            "valueFormatter",
+            "class, className",
+            "...native attributes"
+          ],
+          "available": true,
+          "behavior": {
+            "mode": "registration",
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
+          },
+          "example": "<lumen-pie-chart></lumen-pie-chart>",
+          "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
+          "language": "html",
+          "packageName": "@santi020k/lumen-elements",
+          "props": [],
+          "propsExtends": "HTMLElement attributes",
+          "registration": "defineLumenElements()",
+          "source": "PieChart: {\n    attributeClasses: {\n      ...glassAttributeClasses('ui-chart--glass'),\n      variant: {\n        donut: 'ui-pie-chart--donut',\n        pie: 'ui-pie-chart--pie'\n      }\n    },\n    baseClassName: 'ui-chart ui-pie-chart',\n    defaults: { variant: 'donut' },\n    role: 'figure',\n    tagName: 'lumen-pie-chart'\n  }",
+          "styleImport": "import '@santi020k/lumen-elements/styles.css'",
+          "tagName": "lumen-pie-chart"
+        },
+        "react": {
+          "available": true,
+          "example": "<PieChart aria-label=\"Framework share\" centerLabel=\"Projects\" centerValue=\"2,480\" heading=\"Framework usage\" series={{ id: \"frameworks\", label: \"Framework share\", data: [{ label: \"Astro\", x: \"astro\", y: 46 }, { label: \"React\", x: \"react\", y: 31 }, { label: \"Web Components\", x: \"elements\", y: 23 }] }} />",
+          "importStatement": "import { PieChart } from '@santi020k/lumen-react'",
+          "language": "tsx",
+          "packageName": "@santi020k/lumen-react",
+          "props": [
+            {
+              "name": "centerLabel",
+              "optional": true,
+              "type": "ReactNode"
+            },
+            {
+              "name": "centerValue",
+              "optional": true,
+              "type": "ReactNode"
+            },
+            {
+              "name": "series",
+              "optional": true,
+              "type": "LumenChartSeries"
+            },
+            {
+              "name": "showLegend",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "showTable",
               "optional": true,
-              "type": "string"
+              "type": "boolean"
             },
             {
-              "name": "placeholder",
+              "name": "valueFormatter",
               "optional": true,
-              "type": "string"
+              "type": "(value: number) => string"
             },
             {
-              "name": "size",
+              "name": "variant",
               "optional": true,
-              "type": "'default' | 'lg' | 'sm'"
+              "type": "LumenPieChartVariant"
             }
           ],
-          "propsExtends": "Omit<ComponentPropsWithoutRef<'div'>, 'defaultValue'>",
-          "source": "export interface PhoneInputProps extends Omit<ComponentPropsWithoutRef<'div'>, 'defaultValue'> {\n  countries?: SelectOption[]\n  countryLabel?: string\n  countryName?: string\n  defaultCountryValue?: string\n  defaultValue?: string\n  name?: string\n  placeholder?: string\n  size?: 'default' | 'lg' | 'sm'\n}\n\nexport const PhoneInput = ({\n  className,\n  countries = emptyOptions,\n  countryLabel = 'Country code',\n  countryName = 'country',\n  defaultCountryValue,\n  defaultValue,\n  name = 'phone',\n  placeholder = 'Phone number',\n  size = 'default',\n  ...props\n}: PhoneInputProps) => {\n  const { selectClass, inputClass } = phoneInputSizeModifiers(size)\n\n  return (\n    <div className={composeClassName('ui-phone-input ui-input-group', className)} {...props}>\n      <select\n        aria-label={countryLabel}\n        className={composeClassName('ui-select ui-phone-input__country', selectClass)}\n        defaultValue={defaultCountryValue}\n        name={countryName}\n      >\n        {countries.map(normalizeOption).map(option => (\n          <option disabled={option.disabled} key={option.value} value={option.value}>\n            {option.label}\n          </option>\n        ))}\n      </select>\n      <input\n        autoComplete=\"tel\"\n        className={composeClassName('ui-input ui-phone-input__number', inputClass)}\n        defaultValue={defaultValue}\n        inputMode=\"tel\"\n        name={name}\n        placeholder={placeholder}\n        type=\"tel\"\n      />\n    </div>\n  )\n}",
+          "propsExtends": "Omit<ChartProps, 'children'>",
+          "source": "export interface PieChartProps extends Omit<ChartProps, 'children'> {\n  centerLabel?: ReactNode\n  centerValue?: ReactNode\n  series?: LumenChartSeries\n  showLegend?: boolean\n  showTable?: boolean\n  valueFormatter?: (value: number) => string\n  variant?: LumenPieChartVariant\n}\n\nexport const PieChart = ({\n  centerLabel,\n  centerValue,\n  className,\n  series = emptyPieSeries,\n  showLegend = true,\n  showTable = true,\n  valueFormatter = String,\n  variant = 'donut',\n  ...props\n}: PieChartProps) => {\n  const geometry = createLumenPieGeometry(series.data, { variant })\n  const hasData = hasLumenPieData(series.data)\n\n  return (\n    <Chart\n      className={composeClassName('ui-pie-chart', `ui-pie-chart--${variant}`, className)}\n      {...props}\n    >\n      {showLegend && hasData && (\n        <ul aria-label=\"Chart legend\" className=\"ui-chart__legend\">\n          {geometry.slices.map(slice => (\n            <li\n              className={`ui-chart-tone--${slice.tone}`}\n              key={`${typeof slice.x}:${String(slice.x)}`}\n            >\n              <span aria-hidden=\"true\" />\n              {slice.label}\n            </li>\n          ))}\n        </ul>\n      )}\n      {!hasData && (\n        <p className=\"ui-chart__empty\" role=\"status\">No chart data available.</p>\n      )}\n      <div\n        className=\"ui-chart__plot ui-pie-chart__plot\"\n        hidden={!hasData}\n      >\n        <svg\n          aria-hidden=\"true\"\n          preserveAspectRatio=\"xMidYMid meet\"\n          viewBox={`0 0 ${geometry.size} ${geometry.size}`}\n        >\n          <g className=\"ui-pie-chart__slices\">\n            {geometry.slices.map(slice => (\n              <path\n                className={`ui-chart-tone--${slice.tone}`}\n                d={slice.path}\n                fillRule=\"evenodd\"\n                key={`${typeof slice.x}:${String(slice.x)}`}\n              >\n                <title>\n                  {`${slice.label}: ${valueFormatter(slice.value)} (${formatChartPercentage(slice.percentage)})`}\n                </title>\n              </path>\n            ))}\n          </g>\n        </svg>\n        {variant === 'donut' && (centerLabel != null || centerValue != null) && (\n          <>\n            <div aria-hidden=\"true\" className=\"ui-pie-chart__center\">\n              {centerValue != null && <strong>{centerValue}</strong>}\n              {centerLabel != null && <span>{centerLabel}</span>}\n            </div>\n            <div className=\"ui-sr-only\">\n              {centerValue} {centerLabel}\n            </div>\n          </>\n        )}\n      </div>\n      {showTable && hasData && (\n        <details className=\"ui-chart__data\">\n          <summary>View chart data</summary>\n          <div>\n            <table>\n              <thead>\n                <tr>\n                  <th scope=\"col\">Category</th>\n                  <th scope=\"col\">Value</th>\n                  <th scope=\"col\">Share</th>\n                </tr>\n              </thead>\n              <tbody>\n                {geometry.slices.map(slice => (\n                  <tr key={`${typeof slice.x}:${String(slice.x)}`}>\n                    <th scope=\"row\">{slice.label}</th>\n                    <td>{valueFormatter(slice.value)}</td>\n                    <td>{formatChartPercentage(slice.percentage)}</td>\n                  </tr>\n                ))}\n              </tbody>\n            </table>\n          </div>\n        </details>\n      )}\n    </Chart>\n  )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -11544,90 +12637,144 @@
         "elements": true,
         "react": true
       },
-      "guidance": null,
-      "kebab": "phone-input",
+      "guidance": {
+        "when": "Use for a part-to-whole breakdown with one series, non-negative values, and a small number of meaningful categories.",
+        "distinction": "Prefer the default donut for a center total. Use BarChart when precise comparison or more than roughly seven categories matters, and do not use PieChart for negative values or change over time."
+      },
+      "kebab": "pie-chart",
       "keyboardInteractions": [],
       "keywords": [
-        "built",
-        "choose",
-        "code",
-        "country",
+        "accessible",
+        "and",
+        "barchart",
+        "breakdown",
+        "breakdowns",
+        "categorical",
+        "categories",
+        "center",
+        "change",
+        "chart",
+        "compact",
+        "comparison",
+        "comparisons",
+        "custom",
         "data",
-        "dial",
-        "entry",
-        "field",
-        "forms",
-        "input",
-        "needs",
+        "default",
+        "display",
+        "donut",
+        "for",
+        "match",
+        "matters",
+        "meaningful",
+        "metrics",
+        "more",
+        "negative",
+        "non",
+        "not",
         "number",
-        "only",
-        "pairs",
-        "phoneinput",
-        "purpose",
-        "select",
-        "start",
-        "telephone",
-        "text",
+        "one",
+        "ordered",
+        "over",
+        "part",
+        "pie",
+        "piechart",
+        "plots",
+        "precise",
+        "prefer",
+        "question",
+        "relationships",
+        "roughly",
+        "series",
+        "seven",
+        "shows",
+        "small",
+        "than",
         "the",
-        "then",
+        "time",
+        "total",
+        "trends",
+        "use",
+        "values",
+        "visualization",
         "when",
+        "whole",
         "with"
       ],
-      "name": "PhoneInput",
+      "name": "PieChart",
       "props": [
         {
-          "name": "class",
+          "name": "caption",
           "optional": true,
-          "type": "string | null"
+          "type": "string"
         },
         {
-          "name": "className",
+          "name": "centerLabel",
           "optional": true,
           "type": "string"
         },
         {
-          "name": "countries",
+          "name": "centerValue",
           "optional": true,
-          "type": "Country[]"
+          "type": "string"
         },
         {
-          "name": "countryLabel",
+          "name": "class",
           "optional": true,
-          "type": "string"
+          "type": "string | null"
         },
         {
-          "name": "countryName",
+          "name": "className",
           "optional": true,
           "type": "string"
         },
         {
-          "name": "countryValue",
+          "name": "description",
           "optional": true,
           "type": "string"
         },
         {
-          "name": "name",
+          "name": "glass",
           "optional": true,
-          "type": "string"
+          "type": "boolean | 'subtle' | 'strong'"
         },
         {
-          "name": "placeholder",
+          "name": "heading",
           "optional": true,
           "type": "string"
         },
         {
-          "name": "size",
+          "name": "series",
+          "optional": false,
+          "type": "LumenChartSeries"
+        },
+        {
+          "name": "showLegend",
           "optional": true,
-          "type": "'default' | 'lg' | 'sm'"
+          "type": "boolean"
         },
         {
-          "name": "value",
+          "name": "showTable",
           "optional": true,
-          "type": "string"
+          "type": "boolean"
+        },
+        {
+          "name": "valueFormatter",
+          "optional": true,
+          "type": "(value: number) => string"
+        },
+        {
+          "name": "variant",
+          "optional": true,
+          "type": "LumenPieChartVariant"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'figure'>",
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
         }
       ],
-      "propsExtends": "Omit<HTMLAttributes<'div'>, 'size'>",
-      "recipes": [],
       "runtimeEvents": []
     },
     {
@@ -11644,6 +12791,12 @@
           "description": "Renders the pill as a focusable anchor when it represents a destination.",
           "values": "string"
         },
+        {
+          "attribute": "variant",
+          "defaultValue": "\"neutral\"",
+          "description": "Controls the pill emphasis without changing its metadata semantics.",
+          "values": "\"neutral\" | \"brand\" | \"outline\""
+        },
         {
           "attribute": "class, className",
           "defaultValue": "\"\"",
@@ -11657,7 +12810,7 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  count?: number | string\n  href?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  count,\n  href,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-pill'\n], classProp, className)\n---\n\n{href\n  ? <a class:list={classList} href={href} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </a>\n  : <span class:list={classList} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </span>\n}\n",
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  count?: number | string\n  href?: string\n  variant?: 'brand' | 'neutral' | 'outline'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  count,\n  href,\n  variant = 'neutral',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-pill',\n  variant !== 'neutral' && `ui-pill--${variant}`\n], classProp, className)\n---\n\n{href\n  ? <a class:list={classList} data-variant={variant} href={href} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </a>\n  : <span class:list={classList} data-variant={variant} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </span>\n}\n",
       "category": "Data display",
       "collections": [],
       "dependencies": [
@@ -11671,7 +12824,7 @@
       "frameworkDetails": {
         "astro": {
           "available": true,
-          "example": "<Pill count={12}>Notifications</Pill>",
+          "example": "<Pill count={12} variant=\"brand\">Notifications</Pill>",
           "importStatement": "import { Pill } from '@santi020k/lumen-astro'",
           "language": "astro",
           "packageName": "@santi020k/lumen-astro",
@@ -11695,14 +12848,20 @@
               "name": "href",
               "optional": true,
               "type": "string"
+            },
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "'brand' | 'neutral' | 'outline'"
             }
           ],
           "propsExtends": "HTMLAttributes<'span'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  count?: number | string\n  href?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  count,\n  href,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-pill'\n], classProp, className)\n---\n\n{href\n  ? <a class:list={classList} href={href} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </a>\n  : <span class:list={classList} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </span>\n}\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  class?: string | null\n  className?: string\n  count?: number | string\n  href?: string\n  variant?: 'brand' | 'neutral' | 'outline'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  count,\n  href,\n  variant = 'neutral',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-pill',\n  variant !== 'neutral' && `ui-pill--${variant}`\n], classProp, className)\n---\n\n{href\n  ? <a class:list={classList} data-variant={variant} href={href} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </a>\n  : <span class:list={classList} data-variant={variant} {...passthrough}>\n      <slot />\n      {count != null && <span class=\"ui-pill__count\">{count}</span>}\n    </span>\n}\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
           "attributes": [
+            "variant",
             "count",
             "href",
             "class, className",
@@ -11713,20 +12872,20 @@
             "mode": "registration",
             "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
           },
-          "example": "<lumen-pill count=\"12\">Notifications</lumen-pill>",
+          "example": "<lumen-pill count=\"12\" variant=\"brand\">Notifications</lumen-pill>",
           "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
           "language": "html",
           "packageName": "@santi020k/lumen-elements",
           "props": [],
           "propsExtends": "HTMLElement attributes",
           "registration": "defineLumenElements()",
-          "source": "Pill: { baseClassName: 'ui-pill', tagName: 'lumen-pill' }",
+          "source": "Pill: {\n    attributeClasses: {\n      variant: {\n        brand: 'ui-pill--brand',\n        outline: 'ui-pill--outline'\n      }\n    },\n    baseClassName: 'ui-pill',\n    defaults: { variant: 'neutral' },\n    tagName: 'lumen-pill'\n  }",
           "styleImport": "import '@santi020k/lumen-elements/styles.css'",
           "tagName": "lumen-pill"
         },
         "react": {
           "available": true,
-          "example": "<Pill count={12}>Notifications</Pill>",
+          "example": "<Pill count={12} variant=\"brand\">Notifications</Pill>",
           "importStatement": "import { Pill } from '@santi020k/lumen-react'",
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
@@ -11740,10 +12899,15 @@
               "name": "href",
               "optional": true,
               "type": "string"
+            },
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "'brand' | 'neutral' | 'outline'"
             }
           ],
           "propsExtends": "ComponentPropsWithoutRef<'span'>",
-          "source": "export type PillProps = ComponentPropsWithoutRef<'span'> & {\n  count?: number | string\n  href?: string\n}\n\nexport const Pill = ({ className, count, children, href, ...props }: PillProps) => {\n  const content = (\n    <>\n      {children}\n      {count !== undefined && <span className=\"ui-pill__count\">{count}</span>}\n    </>\n  )\n\n  return href\n    ? <a className={composeClassName('ui-pill', className)} href={href} {...props}>{content}</a>\n    : <span className={composeClassName('ui-pill', className)} {...props}>{content}</span>\n}",
+          "source": "export type PillProps = ComponentPropsWithoutRef<'span'> & {\n  count?: number | string\n  href?: string\n  variant?: 'brand' | 'neutral' | 'outline'\n}\n\nexport const Pill = ({\n  className,\n  count,\n  children,\n  href,\n  variant = 'neutral',\n  ...props\n}: PillProps) => {\n  const content = (\n    <>\n      {children}\n      {count !== undefined && <span className=\"ui-pill__count\">{count}</span>}\n    </>\n  )\n\n  return href\n    ? (\n        <a\n          className={composeClassName('ui-pill', variantClass('ui-pill', variant, 'neutral'), className)}\n          data-variant={variant}\n          href={href}\n          {...props}\n        >\n          {content}\n        </a>\n      )\n    : (\n        <span\n          className={composeClassName('ui-pill', variantClass('ui-pill', variant, 'neutral'), className)}\n          data-variant={variant}\n          {...props}\n        >\n          {content}\n        </span>\n      )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -11808,6 +12972,11 @@
           "name": "href",
           "optional": true,
           "type": "string"
+        },
+        {
+          "name": "variant",
+          "optional": true,
+          "type": "'brand' | 'neutral' | 'outline'"
         }
       ],
       "propsExtends": "HTMLAttributes<'span'>",
@@ -12233,7 +13402,7 @@
       },
       "guidance": {
         "when": "Use to communicate how much of a task, upload, or process has completed.",
-        "distinction": "Use Meter for a stable measurement, Spinner for indeterminate short waits, or Skeleton while page structure is loading."
+        "distinction": "Use ScrollProgress for document position, Meter for a stable measurement, Spinner for indeterminate short waits, or Skeleton while page structure is loading."
       },
       "kebab": "progress",
       "keyboardInteractions": [],
@@ -12241,6 +13410,7 @@
         "communicate",
         "completed",
         "completion",
+        "document",
         "feedback",
         "for",
         "has",
@@ -12251,9 +13421,11 @@
         "meter",
         "much",
         "page",
+        "position",
         "process",
         "progress",
         "quota",
+        "scrollprogress",
         "short",
         "shows",
         "skeleton",
@@ -13215,22 +14387,175 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  glass?: boolean | 'subtle' | 'strong'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  glass = false,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-scroll-area',\n    glass && 'ui-scroll-area--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
-      "category": "Layout",
-      "collections": [],
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  glass?: boolean | 'subtle' | 'strong'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  glass = false,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-scroll-area',\n    glass && 'ui-scroll-area--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+      "category": "Layout",
+      "collections": [],
+      "dependencies": [
+        "styles"
+      ],
+      "description": "Provides a styled scroll container.",
+      "files": [
+        "packages/astro/components/ScrollArea.astro",
+        "packages/astro/styles/lumen.css"
+      ],
+      "frameworkDetails": {
+        "astro": {
+          "available": true,
+          "example": "<ScrollArea style=\"max-height: 18rem\"><p>Long release notes...</p></ScrollArea>",
+          "importStatement": "import { ScrollArea } from '@santi020k/lumen-astro'",
+          "language": "astro",
+          "packageName": "@santi020k/lumen-astro",
+          "props": [
+            {
+              "name": "class",
+              "optional": true,
+              "type": "string | null"
+            },
+            {
+              "name": "className",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "glass",
+              "optional": true,
+              "type": "boolean | 'subtle' | 'strong'"
+            }
+          ],
+          "propsExtends": "HTMLAttributes<'div'>",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  glass?: boolean | 'subtle' | 'strong'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  glass = false,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-scroll-area',\n    glass && 'ui-scroll-area--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+          "styleImport": "import '@santi020k/lumen-astro/styles.css'"
+        },
+        "elements": {
+          "attributes": [
+            "glass",
+            "children",
+            "class, className",
+            "...native attributes"
+          ],
+          "available": true,
+          "behavior": {
+            "mode": "registration",
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
+          },
+          "example": "<lumen-scroll-area style=\"max-height: 18rem\"><p>Long release notes...</p></lumen-scroll-area>",
+          "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
+          "language": "html",
+          "packageName": "@santi020k/lumen-elements",
+          "props": [],
+          "propsExtends": "HTMLElement attributes",
+          "registration": "defineLumenElements()",
+          "source": "ScrollArea: { attributeClasses: glassAttributeClasses('ui-scroll-area--glass'), baseClassName: 'ui-scroll-area', tagName: 'lumen-scroll-area' }",
+          "styleImport": "import '@santi020k/lumen-elements/styles.css'",
+          "tagName": "lumen-scroll-area"
+        },
+        "react": {
+          "available": true,
+          "example": "<ScrollArea style={{ maxHeight: '18rem' }}><p>Long release notes...</p></ScrollArea>",
+          "importStatement": "import { ScrollArea } from '@santi020k/lumen-react'",
+          "language": "tsx",
+          "packageName": "@santi020k/lumen-react",
+          "props": [
+            {
+              "name": "glass",
+              "optional": true,
+              "type": "LumenGlassProp"
+            }
+          ],
+          "propsExtends": "ComponentPropsWithoutRef<'div'>",
+          "source": "export interface ScrollAreaProps extends ComponentPropsWithoutRef<'div'> {\n  glass?: LumenGlassProp\n}\n\nexport const ScrollArea = ({ className, glass = false, ...props }: ScrollAreaProps) => (\n  <div className={composeClassName('ui-scroll-area', glassClass('ui-scroll-area', glass), className)} {...props} />\n)",
+          "styleImport": "import '@santi020k/lumen-react/styles.css'"
+        }
+      },
+      "frameworks": {
+        "astro": true,
+        "elements": true,
+        "react": true
+      },
+      "guidance": null,
+      "kebab": "scroll-area",
+      "keyboardInteractions": [],
+      "keywords": [
+        "container",
+        "layout",
+        "provides",
+        "scroll",
+        "scrollarea",
+        "styled"
+      ],
+      "name": "ScrollArea",
+      "props": [
+        {
+          "name": "class",
+          "optional": true,
+          "type": "string | null"
+        },
+        {
+          "name": "className",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "glass",
+          "optional": true,
+          "type": "boolean | 'subtle' | 'strong'"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'div'>",
+      "recipes": [],
+      "runtimeEvents": []
+    },
+    {
+      "apiReference": [
+        {
+          "attribute": "position",
+          "defaultValue": "\"top\"",
+          "description": "Pins the progress indicator to a viewport edge.",
+          "values": "\"top\" | \"bottom\""
+        },
+        {
+          "attribute": "aria-label",
+          "defaultValue": "\"Reading progress\"",
+          "description": "Names the live document-progress indicator for assistive technology.",
+          "values": "string"
+        },
+        {
+          "attribute": "class, className",
+          "defaultValue": "\"\"",
+          "description": "Merges custom classes with the generated ui-* root classes.",
+          "values": "string"
+        },
+        {
+          "attribute": "...native attributes",
+          "defaultValue": "-",
+          "description": "Forwards standard attributes to the root element unless the component consumes them.",
+          "values": "HTML attributes"
+        }
+      ],
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  position?: 'bottom' | 'top'\n}\n\nconst {\n  'aria-label': ariaLabel = 'Reading progress',\n  class: classProp = '',\n  className = '',\n  position = 'top',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-scroll-progress',\n  position === 'bottom' && 'ui-scroll-progress--bottom'\n], classProp, className)\n---\n\n<div\n  aria-label={ariaLabel}\n  aria-valuemax=\"100\"\n  aria-valuemin=\"0\"\n  aria-valuenow=\"0\"\n  class:list={classList}\n  data-position={position}\n  data-ui-scroll-progress\n  role=\"progressbar\"\n  {...passthrough}\n>\n  <span class=\"ui-scroll-progress__bar\"></span>\n</div>\n",
+      "category": "Feedback",
+      "collections": [
+        "Status and messaging"
+      ],
       "dependencies": [
-        "styles"
+        "styles",
+        "runtime"
       ],
-      "description": "Provides a styled scroll container.",
+      "description": "Shows the reader’s current position in a long document.",
       "files": [
-        "packages/astro/components/ScrollArea.astro",
-        "packages/astro/styles/lumen.css"
+        "packages/astro/components/ScrollProgress.astro",
+        "packages/astro/styles/lumen.css",
+        "packages/astro/runtime/UIPrimitives.astro"
       ],
       "frameworkDetails": {
         "astro": {
           "available": true,
-          "example": "<ScrollArea style=\"max-height: 18rem\"><p>Long release notes...</p></ScrollArea>",
-          "importStatement": "import { ScrollArea } from '@santi020k/lumen-astro'",
+          "behavior": {
+            "mode": "runtime",
+            "setup": "Mount UIPrimitives once in the application's root layout; do not mount it beside each component."
+          },
+          "example": "<ScrollProgress aria-label=\"Article reading progress\" />",
+          "importStatement": "import { ScrollProgress } from '@santi020k/lumen-astro'",
           "language": "astro",
           "packageName": "@santi020k/lumen-astro",
           "props": [
@@ -13245,53 +14570,62 @@
               "type": "string"
             },
             {
-              "name": "glass",
+              "name": "position",
               "optional": true,
-              "type": "boolean | 'subtle' | 'strong'"
+              "type": "'bottom' | 'top'"
             }
           ],
           "propsExtends": "HTMLAttributes<'div'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  glass?: boolean | 'subtle' | 'strong'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  glass = false,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-scroll-area',\n    glass && 'ui-scroll-area--glass',\n    glass === 'subtle' && 'ui-glass-subtle',\n    glass === 'strong' && 'ui-glass-strong'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  position?: 'bottom' | 'top'\n}\n\nconst {\n  'aria-label': ariaLabel = 'Reading progress',\n  class: classProp = '',\n  className = '',\n  position = 'top',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-scroll-progress',\n  position === 'bottom' && 'ui-scroll-progress--bottom'\n], classProp, className)\n---\n\n<div\n  aria-label={ariaLabel}\n  aria-valuemax=\"100\"\n  aria-valuemin=\"0\"\n  aria-valuenow=\"0\"\n  class:list={classList}\n  data-position={position}\n  data-ui-scroll-progress\n  role=\"progressbar\"\n  {...passthrough}\n>\n  <span class=\"ui-scroll-progress__bar\"></span>\n</div>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
           "attributes": [
-            "glass",
-            "children",
+            "aria-label",
+            "aria-valuemax",
+            "aria-valuemin",
+            "aria-valuenow",
+            "data-ui-scroll-progress",
+            "position",
+            "role",
             "class, className",
             "...native attributes"
           ],
           "available": true,
           "behavior": {
             "mode": "registration",
-            "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements. Registration includes this component’s interactive behavior."
           },
-          "example": "<lumen-scroll-area style=\"max-height: 18rem\"><p>Long release notes...</p></lumen-scroll-area>",
+          "example": "<lumen-scroll-progress aria-label=\"Article reading progress\"></lumen-scroll-progress>",
           "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
           "language": "html",
           "packageName": "@santi020k/lumen-elements",
           "props": [],
           "propsExtends": "HTMLElement attributes",
           "registration": "defineLumenElements()",
-          "source": "ScrollArea: { attributeClasses: glassAttributeClasses('ui-scroll-area--glass'), baseClassName: 'ui-scroll-area', tagName: 'lumen-scroll-area' }",
+          "source": "ScrollProgress: {\n    attributeClasses: {\n      position: { bottom: 'ui-scroll-progress--bottom' }\n    },\n    baseClassName: 'ui-scroll-progress',\n    defaults: {\n      'aria-label': 'Reading progress',\n      'aria-valuemax': '100',\n      'aria-valuemin': '0',\n      'aria-valuenow': '0',\n      'data-ui-scroll-progress': '',\n      position: 'top',\n      role: 'progressbar'\n    },\n    tagName: 'lumen-scroll-progress'\n  }",
           "styleImport": "import '@santi020k/lumen-elements/styles.css'",
-          "tagName": "lumen-scroll-area"
+          "tagName": "lumen-scroll-progress"
         },
         "react": {
           "available": true,
-          "example": "<ScrollArea style={{ maxHeight: '18rem' }}><p>Long release notes...</p></ScrollArea>",
-          "importStatement": "import { ScrollArea } from '@santi020k/lumen-react'",
+          "behavior": {
+            "mode": "built-in",
+            "setup": "Interactive behavior is implemented by the React component; do not mount Astro UIPrimitives."
+          },
+          "example": "<ScrollProgress aria-label=\"Article reading progress\" />",
+          "importStatement": "import { ScrollProgress } from '@santi020k/lumen-react'",
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
           "props": [
             {
-              "name": "glass",
+              "name": "position",
               "optional": true,
-              "type": "LumenGlassProp"
+              "type": "'bottom' | 'top'"
             }
           ],
           "propsExtends": "ComponentPropsWithoutRef<'div'>",
-          "source": "export interface ScrollAreaProps extends ComponentPropsWithoutRef<'div'> {\n  glass?: LumenGlassProp\n}\n\nexport const ScrollArea = ({ className, glass = false, ...props }: ScrollAreaProps) => (\n  <div className={composeClassName('ui-scroll-area', glassClass('ui-scroll-area', glass), className)} {...props} />\n)",
+          "source": "export interface ScrollProgressProps extends ComponentPropsWithoutRef<'div'> {\n  position?: 'bottom' | 'top'\n}\n\nexport const ScrollProgress = ({\n  'aria-label': ariaLabel = 'Reading progress',\n  className,\n  position = 'top',\n  ...props\n}: ScrollProgressProps) => {\n  const rootRef = useRef<HTMLDivElement>(null)\n\n  useEffect(() => {\n    const root = rootRef.current\n\n    if (!root) return\n\n    let frame = 0\n\n    const update = () => {\n      frame = 0\n\n      const scrollingElement = document.scrollingElement ?? document.documentElement\n      const maximum = scrollingElement.scrollHeight - scrollingElement.clientHeight\n\n      const percentage = maximum > 0\n        ? Math.min(100, Math.max(0, (scrollingElement.scrollTop / maximum) * 100))\n        : 0\n\n      const bar = root.querySelector<HTMLElement>('.ui-scroll-progress__bar')\n\n      root.setAttribute('aria-valuenow', `${Math.round(percentage)}`)\n\n      if (bar) bar.style.transform = `scaleX(${percentage / 100})`\n    }\n\n    const scheduleUpdate = () => {\n      if (frame) return\n\n      frame = window.requestAnimationFrame(update)\n    }\n\n    scheduleUpdate()\n\n    window.addEventListener('resize', scheduleUpdate, { passive: true })\n\n    window.addEventListener('scroll', scheduleUpdate, { passive: true })\n\n    return () => {\n      if (frame) window.cancelAnimationFrame(frame)\n\n      window.removeEventListener('resize', scheduleUpdate)\n\n      window.removeEventListener('scroll', scheduleUpdate)\n    }\n  }, [])\n\n  return (\n    <div\n      aria-label={ariaLabel}\n      aria-valuemax={100}\n      aria-valuemin={0}\n      aria-valuenow={0}\n      className={composeClassName(\n        'ui-scroll-progress',\n        position === 'bottom' && 'ui-scroll-progress--bottom',\n        className\n      )}\n      data-position={position}\n      data-ui-scroll-progress\n      ref={rootRef}\n      role=\"progressbar\"\n      {...props}\n    >\n      <span className=\"ui-scroll-progress__bar\" />\n    </div>\n  )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -13300,18 +14634,60 @@
         "elements": true,
         "react": true
       },
-      "guidance": null,
-      "kebab": "scroll-area",
+      "guidance": {
+        "when": "Use on long reading surfaces when readers benefit from knowing how far they have moved through the current document.",
+        "distinction": "Use Progress for task completion supplied by application state. ScrollProgress derives its value from the document scroll position."
+      },
+      "kebab": "scroll-progress",
       "keyboardInteractions": [],
       "keywords": [
-        "container",
-        "layout",
-        "provides",
+        "and",
+        "application",
+        "benefit",
+        "completion",
+        "current",
+        "derives",
+        "document",
+        "empty",
+        "far",
+        "feedback",
+        "for",
+        "from",
+        "guidance",
+        "have",
+        "how",
+        "inline",
+        "its",
+        "knowing",
+        "long",
+        "messaging",
+        "moved",
+        "notifications",
+        "persistent",
+        "position",
+        "progress",
+        "reader",
+        "readers",
+        "reading",
         "scroll",
-        "scrollarea",
-        "styled"
+        "scrollprogress",
+        "separate",
+        "shows",
+        "state",
+        "states",
+        "status",
+        "supplied",
+        "surfaces",
+        "task",
+        "the",
+        "they",
+        "through",
+        "transient",
+        "use",
+        "value",
+        "when"
       ],
-      "name": "ScrollArea",
+      "name": "ScrollProgress",
       "props": [
         {
           "name": "class",
@@ -13324,9 +14700,9 @@
           "type": "string"
         },
         {
-          "name": "glass",
+          "name": "position",
           "optional": true,
-          "type": "boolean | 'subtle' | 'strong'"
+          "type": "'bottom' | 'top'"
         }
       ],
       "propsExtends": "HTMLAttributes<'div'>",
@@ -15199,47 +16575,224 @@
       "name": "Slider",
       "props": [
         {
-          "name": "class",
-          "optional": true,
-          "type": "string | null"
+          "name": "class",
+          "optional": true,
+          "type": "string | null"
+        },
+        {
+          "name": "className",
+          "optional": true,
+          "type": "string"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'input'>",
+      "recipes": [],
+      "runtimeEvents": []
+    },
+    {
+      "apiReference": [],
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  maxCount?: number\n  placement?: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'\n}\n\nconst {\n  'aria-atomic': ariaAtomic = 'false',\n  'aria-live': ariaLive = 'polite',\n  class: classProp = '',\n  className = '',\n  maxCount,\n  placement = 'bottom-right',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-sonner'\n], classProp, className)\n---\n\n<div\n  aria-atomic={ariaAtomic}\n  aria-live={ariaLive}\n  data-ui-sonner\n  data-ui-toast-max={maxCount}\n  data-placement={placement}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+      "category": "Feedback",
+      "collections": [],
+      "dependencies": [
+        "styles",
+        "runtime"
+      ],
+      "description": "Provides the toast viewport for notifications.",
+      "files": [
+        "packages/astro/components/Sonner.astro",
+        "packages/astro/styles/lumen.css",
+        "packages/astro/runtime/UIPrimitives.astro"
+      ],
+      "frameworkDetails": {
+        "astro": {
+          "available": true,
+          "behavior": {
+            "mode": "runtime",
+            "setup": "Mount UIPrimitives once in the application's root layout; do not mount it beside each component."
+          },
+          "example": "<Sonner />",
+          "importStatement": "import { Sonner } from '@santi020k/lumen-astro'",
+          "language": "astro",
+          "packageName": "@santi020k/lumen-astro",
+          "props": [
+            {
+              "name": "class",
+              "optional": true,
+              "type": "string | null"
+            },
+            {
+              "name": "className",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "maxCount",
+              "optional": true,
+              "type": "number"
+            },
+            {
+              "name": "placement",
+              "optional": true,
+              "type": "'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'"
+            }
+          ],
+          "propsExtends": "HTMLAttributes<'div'>",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  maxCount?: number\n  placement?: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'\n}\n\nconst {\n  'aria-atomic': ariaAtomic = 'false',\n  'aria-live': ariaLive = 'polite',\n  class: classProp = '',\n  className = '',\n  maxCount,\n  placement = 'bottom-right',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-sonner'\n], classProp, className)\n---\n\n<div\n  aria-atomic={ariaAtomic}\n  aria-live={ariaLive}\n  data-ui-sonner\n  data-ui-toast-max={maxCount}\n  data-placement={placement}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+          "styleImport": "import '@santi020k/lumen-astro/styles.css'"
+        },
+        "elements": {
+          "attributes": [
+            "data-ui-sonner"
+          ],
+          "available": true,
+          "behavior": {
+            "mode": "registration",
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements. Registration includes this component’s interactive behavior."
+          },
+          "example": "<lumen-sonner></lumen-sonner>",
+          "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
+          "language": "html",
+          "packageName": "@santi020k/lumen-elements",
+          "props": [],
+          "propsExtends": "HTMLElement attributes",
+          "registration": "defineLumenElements()",
+          "source": "Sonner: { baseClassName: 'ui-sonner', defaults: { 'data-ui-sonner': '' }, tagName: 'lumen-sonner' }",
+          "styleImport": "import '@santi020k/lumen-elements/styles.css'",
+          "tagName": "lumen-sonner"
+        },
+        "react": {
+          "available": true,
+          "behavior": {
+            "mode": "adapter",
+            "setup": "The React component exposes the documented data attributes; app-level state must implement the documented interactive and event behavior. Do not mount Astro UIPrimitives."
+          },
+          "example": "<Sonner />",
+          "importStatement": "import { Sonner } from '@santi020k/lumen-react'",
+          "language": "tsx",
+          "packageName": "@santi020k/lumen-react",
+          "props": [],
+          "propsExtends": "ComponentPropsWithoutRef<'div'>",
+          "source": "export type SonnerProps = ComponentPropsWithoutRef<'div'>\n\nexport const Sonner = ({ className, ...props }: SonnerProps) => (\n  <div className={composeClassName('ui-sonner', className)} data-ui-sonner {...props} />\n)",
+          "styleImport": "import '@santi020k/lumen-react/styles.css'"
+        }
+      },
+      "frameworks": {
+        "astro": true,
+        "elements": true,
+        "react": true
+      },
+      "guidance": null,
+      "kebab": "sonner",
+      "keyboardInteractions": [],
+      "keywords": [
+        "feedback",
+        "for",
+        "notifications",
+        "provides",
+        "sonner",
+        "the",
+        "toast",
+        "viewport"
+      ],
+      "name": "Sonner",
+      "props": [
+        {
+          "name": "class",
+          "optional": true,
+          "type": "string | null"
+        },
+        {
+          "name": "className",
+          "optional": true,
+          "type": "string"
+        },
+        {
+          "name": "maxCount",
+          "optional": true,
+          "type": "number"
+        },
+        {
+          "name": "placement",
+          "optional": true,
+          "type": "'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'div'>",
+      "recipes": [],
+      "runtimeEvents": []
+    },
+    {
+      "apiReference": [
+        {
+          "attribute": "values",
+          "defaultValue": "required",
+          "description": "Provides ordered values for the compact trend.",
+          "values": "number[]"
+        },
+        {
+          "attribute": "label",
+          "defaultValue": "required",
+          "description": "Communicates the trend in text because the SVG is intentionally decorative.",
+          "values": "string"
+        },
+        {
+          "attribute": "area",
+          "defaultValue": "false",
+          "description": "Adds a subtle tokenized fill below the line.",
+          "values": "boolean"
         },
         {
-          "name": "className",
-          "optional": true,
-          "type": "string"
+          "attribute": "showEndpoint",
+          "defaultValue": "true",
+          "description": "Marks the latest value with a color-independent endpoint.",
+          "values": "boolean"
+        },
+        {
+          "attribute": "tone",
+          "defaultValue": "\"series-1\"",
+          "description": "Selects a categorical or explicitly semantic chart tone.",
+          "values": "LumenChartTone"
+        },
+        {
+          "attribute": "class, className",
+          "defaultValue": "\"\"",
+          "description": "Merges custom classes with the generated ui-* root classes.",
+          "values": "string"
+        },
+        {
+          "attribute": "...native attributes",
+          "defaultValue": "-",
+          "description": "Forwards standard attributes to the root element unless the component consumes them.",
+          "values": "HTML attributes"
         }
       ],
-      "propsExtends": "HTMLAttributes<'input'>",
-      "recipes": [],
-      "runtimeEvents": []
-    },
-    {
-      "apiReference": [],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  maxCount?: number\n  placement?: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'\n}\n\nconst {\n  'aria-atomic': ariaAtomic = 'false',\n  'aria-live': ariaLive = 'polite',\n  class: classProp = '',\n  className = '',\n  maxCount,\n  placement = 'bottom-right',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-sonner'\n], classProp, className)\n---\n\n<div\n  aria-atomic={ariaAtomic}\n  aria-live={ariaLive}\n  data-ui-sonner\n  data-ui-toast-max={maxCount}\n  data-placement={placement}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
-      "category": "Feedback",
-      "collections": [],
+      "astroSource": "---\nimport {\n  composeClassName,\n  createLumenLineGeometry,\n  type LumenChartTone,\n  resolveLumenChartTone\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  area?: boolean\n  class?: string | null\n  className?: string\n  label: string\n  showEndpoint?: boolean\n  tone?: LumenChartTone\n  values: readonly number[]\n}\n\nconst {\n  area = false,\n  class: classProp = '',\n  className = '',\n  label,\n  showEndpoint = true,\n  tone,\n  values,\n  ...rest\n} = Astro.props\nconst data = values.map((value, index) => ({ x: index, y: value }))\nconst geometry = createLumenLineGeometry(data, {\n  height: 40,\n  padding: 3,\n  width: 120\n})\nconst resolvedTone = resolveLumenChartTone(tone)\nconst endpoint = geometry.points[geometry.points.length - 1]\n---\n\n<span\n  aria-label={label}\n  class={composeClassName(\n    'ui-sparkline',\n    `ui-chart-tone--${resolvedTone}`,\n    classProp,\n    className\n  )}\n  role=\"img\"\n  {...rest}\n>\n  <svg aria-hidden=\"true\" preserveAspectRatio=\"none\" viewBox=\"0 0 120 40\">\n    {\n      area &&\n        geometry.areaPaths.map((path) => (\n          <path class=\"ui-sparkline__area\" d={path} />\n        ))\n    }\n    <path class=\"ui-sparkline__line\" d={geometry.path} />\n    {\n      showEndpoint && endpoint && (\n        <circle\n          class=\"ui-sparkline__endpoint\"\n          cx={endpoint.xCoordinate}\n          cy={endpoint.yCoordinate}\n          r=\"2.5\"\n        />\n      )\n    }\n  </svg>\n  <span class=\"ui-sr-only\">{label}</span>\n</span>\n",
+      "category": "Data display",
+      "collections": [
+        "Data visualization"
+      ],
       "dependencies": [
-        "styles",
-        "runtime"
+        "styles"
       ],
-      "description": "Provides the toast viewport for notifications.",
+      "description": "Shows a compact, text-labelled trend beside an existing metric.",
       "files": [
-        "packages/astro/components/Sonner.astro",
-        "packages/astro/styles/lumen.css",
-        "packages/astro/runtime/UIPrimitives.astro"
+        "packages/astro/components/Sparkline.astro",
+        "packages/astro/styles/lumen.css"
       ],
       "frameworkDetails": {
         "astro": {
           "available": true,
-          "behavior": {
-            "mode": "runtime",
-            "setup": "Mount UIPrimitives once in the application's root layout; do not mount it beside each component."
-          },
-          "example": "<Sonner />",
-          "importStatement": "import { Sonner } from '@santi020k/lumen-astro'",
+          "example": "<Sparkline label=\"Downloads increased from 42 to 91\" values={[42, 48, 63, 58, 74, 91]} area />",
+          "importStatement": "import { Sparkline } from '@santi020k/lumen-astro'",
           "language": "astro",
           "packageName": "@santi020k/lumen-astro",
           "props": [
+            {
+              "name": "area",
+              "optional": true,
+              "type": "boolean"
+            },
             {
               "name": "class",
               "optional": true,
@@ -15251,53 +16804,91 @@
               "type": "string"
             },
             {
-              "name": "maxCount",
+              "name": "label",
+              "optional": false,
+              "type": "string"
+            },
+            {
+              "name": "showEndpoint",
               "optional": true,
-              "type": "number"
+              "type": "boolean"
             },
             {
-              "name": "placement",
+              "name": "tone",
               "optional": true,
-              "type": "'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'"
+              "type": "LumenChartTone"
+            },
+            {
+              "name": "values",
+              "optional": false,
+              "type": "readonly number[]"
             }
           ],
-          "propsExtends": "HTMLAttributes<'div'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  maxCount?: number\n  placement?: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'\n}\n\nconst {\n  'aria-atomic': ariaAtomic = 'false',\n  'aria-live': ariaLive = 'polite',\n  class: classProp = '',\n  className = '',\n  maxCount,\n  placement = 'bottom-right',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n    'ui-sonner'\n], classProp, className)\n---\n\n<div\n  aria-atomic={ariaAtomic}\n  aria-live={ariaLive}\n  data-ui-sonner\n  data-ui-toast-max={maxCount}\n  data-placement={placement}\n  class:list={classList}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+          "propsExtends": "HTMLAttributes<'span'>",
+          "source": "---\nimport {\n  composeClassName,\n  createLumenLineGeometry,\n  type LumenChartTone,\n  resolveLumenChartTone\n} from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'span'> {\n  area?: boolean\n  class?: string | null\n  className?: string\n  label: string\n  showEndpoint?: boolean\n  tone?: LumenChartTone\n  values: readonly number[]\n}\n\nconst {\n  area = false,\n  class: classProp = '',\n  className = '',\n  label,\n  showEndpoint = true,\n  tone,\n  values,\n  ...rest\n} = Astro.props\nconst data = values.map((value, index) => ({ x: index, y: value }))\nconst geometry = createLumenLineGeometry(data, {\n  height: 40,\n  padding: 3,\n  width: 120\n})\nconst resolvedTone = resolveLumenChartTone(tone)\nconst endpoint = geometry.points[geometry.points.length - 1]\n---\n\n<span\n  aria-label={label}\n  class={composeClassName(\n    'ui-sparkline',\n    `ui-chart-tone--${resolvedTone}`,\n    classProp,\n    className\n  )}\n  role=\"img\"\n  {...rest}\n>\n  <svg aria-hidden=\"true\" preserveAspectRatio=\"none\" viewBox=\"0 0 120 40\">\n    {\n      area &&\n        geometry.areaPaths.map((path) => (\n          <path class=\"ui-sparkline__area\" d={path} />\n        ))\n    }\n    <path class=\"ui-sparkline__line\" d={geometry.path} />\n    {\n      showEndpoint && endpoint && (\n        <circle\n          class=\"ui-sparkline__endpoint\"\n          cx={endpoint.xCoordinate}\n          cy={endpoint.yCoordinate}\n          r=\"2.5\"\n        />\n      )\n    }\n  </svg>\n  <span class=\"ui-sr-only\">{label}</span>\n</span>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
           "attributes": [
-            "data-ui-sonner"
+            "values",
+            "label",
+            "area",
+            "showEndpoint",
+            "tone",
+            "class, className",
+            "...native attributes"
           ],
           "available": true,
           "behavior": {
             "mode": "registration",
-            "setup": "Call defineLumenElements() once before rendering Lumen custom elements. Registration includes this component’s interactive behavior."
+            "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
           },
-          "example": "<lumen-sonner></lumen-sonner>",
+          "example": "<lumen-sparkline></lumen-sparkline>",
           "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
           "language": "html",
           "packageName": "@santi020k/lumen-elements",
           "props": [],
           "propsExtends": "HTMLElement attributes",
           "registration": "defineLumenElements()",
-          "source": "Sonner: { baseClassName: 'ui-sonner', defaults: { 'data-ui-sonner': '' }, tagName: 'lumen-sonner' }",
+          "source": "Sparkline: { baseClassName: 'ui-sparkline', tagName: 'lumen-sparkline' }",
           "styleImport": "import '@santi020k/lumen-elements/styles.css'",
-          "tagName": "lumen-sonner"
+          "tagName": "lumen-sparkline"
         },
         "react": {
           "available": true,
-          "behavior": {
-            "mode": "adapter",
-            "setup": "The React component exposes the documented data attributes; app-level state must implement the documented interactive and event behavior. Do not mount Astro UIPrimitives."
-          },
-          "example": "<Sonner />",
-          "importStatement": "import { Sonner } from '@santi020k/lumen-react'",
+          "example": "<Sparkline label=\"Downloads increased from 42 to 91\" values={[42, 48, 63, 58, 74, 91]} area />",
+          "importStatement": "import { Sparkline } from '@santi020k/lumen-react'",
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
-          "props": [],
-          "propsExtends": "ComponentPropsWithoutRef<'div'>",
-          "source": "export type SonnerProps = ComponentPropsWithoutRef<'div'>\n\nexport const Sonner = ({ className, ...props }: SonnerProps) => (\n  <div className={composeClassName('ui-sonner', className)} data-ui-sonner {...props} />\n)",
+          "props": [
+            {
+              "name": "area",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "label",
+              "optional": true,
+              "type": "string"
+            },
+            {
+              "name": "showEndpoint",
+              "optional": true,
+              "type": "boolean"
+            },
+            {
+              "name": "tone",
+              "optional": true,
+              "type": "LumenChartTone"
+            },
+            {
+              "name": "values",
+              "optional": true,
+              "type": "readonly number[]"
+            }
+          ],
+          "propsExtends": "Omit<ComponentPropsWithoutRef<'span'>, 'children'>",
+          "source": "export interface SparklineProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {\n  area?: boolean\n  label?: string\n  showEndpoint?: boolean\n  tone?: LumenChartTone\n  values?: readonly number[]\n}\n\nexport const Sparkline = ({\n  area = false,\n  className,\n  label = 'Trend',\n  showEndpoint = true,\n  tone,\n  values = emptyChartValues,\n  ...props\n}: SparklineProps) => {\n  const geometry = createLumenLineGeometry(\n    values.map((value, index) => ({ x: index, y: value })),\n    { height: 40, padding: 3, width: 120 }\n  )\n\n  const resolvedTone = resolveLumenChartTone(tone)\n  const endpoint = geometry.points.at(-1)\n\n  return (\n    <span\n      aria-label={label}\n      className={composeClassName('ui-sparkline', `ui-chart-tone--${resolvedTone}`, className)}\n      role=\"img\"\n      {...props}\n    >\n      <svg aria-hidden=\"true\" preserveAspectRatio=\"none\" viewBox=\"0 0 120 40\">\n        {area && geometry.areaPaths.map(path => (\n          <path className=\"ui-sparkline__area\" d={path} key={path} />\n        ))}\n        <path className=\"ui-sparkline__line\" d={geometry.path} />\n        {showEndpoint && endpoint && (\n          <circle\n            className=\"ui-sparkline__endpoint\"\n            cx={endpoint.xCoordinate}\n            cy={endpoint.yCoordinate}\n            r=\"2.5\"\n          />\n        )}\n      </svg>\n      <span className=\"ui-sr-only\">{label}</span>\n    </span>\n  )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -15306,21 +16897,66 @@
         "elements": true,
         "react": true
       },
-      "guidance": null,
-      "kebab": "sonner",
+      "guidance": {
+        "when": "Use beside a metric when a compact trend adds meaning and at least two valid samples exist.",
+        "distinction": "Use LineChart when axes, multiple series, thresholds, exact values, or a data table are important."
+      },
+      "kebab": "sparkline",
       "keyboardInteractions": [],
       "keywords": [
-        "feedback",
-        "for",
-        "notifications",
-        "provides",
-        "sonner",
+        "adds",
+        "and",
+        "are",
+        "axes",
+        "beside",
+        "breakdowns",
+        "categorical",
+        "compact",
+        "comparisons",
+        "custom",
+        "data",
+        "display",
+        "exact",
+        "exist",
+        "existing",
+        "important",
+        "labelled",
+        "least",
+        "linechart",
+        "match",
+        "meaning",
+        "metric",
+        "metrics",
+        "multiple",
+        "ordered",
+        "part",
+        "plots",
+        "question",
+        "samples",
+        "series",
+        "shows",
+        "sparkline",
+        "table",
+        "text",
         "the",
-        "toast",
-        "viewport"
+        "thresholds",
+        "trend",
+        "trends",
+        "two",
+        "use",
+        "valid",
+        "values",
+        "visualization",
+        "when",
+        "whole"
       ],
-      "name": "Sonner",
+      "name": "Sparkline",
       "props": [
+        {
+          "name": "area",
+          "optional": true,
+          "type": "boolean"
+        },
         {
           "name": "class",
           "optional": true,
@@ -15332,18 +16968,33 @@
           "type": "string"
         },
         {
-          "name": "maxCount",
+          "name": "label",
+          "optional": false,
+          "type": "string"
+        },
+        {
+          "name": "showEndpoint",
           "optional": true,
-          "type": "number"
+          "type": "boolean"
         },
         {
-          "name": "placement",
+          "name": "tone",
           "optional": true,
-          "type": "'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'"
+          "type": "LumenChartTone"
+        },
+        {
+          "name": "values",
+          "optional": false,
+          "type": "readonly number[]"
+        }
+      ],
+      "propsExtends": "HTMLAttributes<'span'>",
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
         }
       ],
-      "propsExtends": "HTMLAttributes<'div'>",
-      "recipes": [],
       "runtimeEvents": []
     },
     {
@@ -18889,7 +20540,7 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  density?: 'low' | 'medium' | 'high'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  density = 'medium',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-particles'\n], classProp, className)\n---\n\n<div\n  aria-hidden=\"true\"\n  class:list={classList}\n  data-ui-particles={density}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  density?: 'low' | 'medium' | 'high'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  density = 'medium',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-particles'\n], classProp, className)\n---\n\n<div\n  aria-hidden=\"true\"\n  class:list={classList}\n  data-ui-particles={density}\n  {...passthrough}\n>\n  <slot />\n</div>\n\n<script>\n  type ParticleDensity = 'low' | 'medium' | 'high'\n\n  const densityConfig: Record<ParticleDensity, number> = {\n    low: 15,\n    medium: 25,\n    high: 40\n  }\n\n  const particleTones = [\n    'var(--brand)',\n    'var(--accent)',\n    'var(--glow, var(--brand))'\n  ]\n\n  const initParticles = (scope: ParentNode = document) => {\n    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return\n\n    for (const container of scope.querySelectorAll<HTMLElement>('[data-ui-particles]')) {\n      if (container.hasAttribute('data-ui-particles-initialized')) continue\n\n      container.setAttribute('data-ui-particles-initialized', '')\n\n      const density = (container.dataset.uiParticles || 'medium') as ParticleDensity\n      const count = densityConfig[density]\n\n      for (let index = 0; index < count; index++) {\n        const particle = document.createElement('span')\n        const size = Math.random() * 12 + 8\n\n        particle.className = 'ui-particles__particle'\n        particle.style.setProperty('--ui-particle-delay', `${Math.random() * 8}s`)\n        particle.style.setProperty('--ui-particle-duration', `${20 + Math.random() * 15}s`)\n        particle.style.setProperty('--ui-particle-left', `${Math.random() * 100}%`)\n        particle.style.setProperty('--ui-particle-size', `${size}px`)\n        particle.style.setProperty('--ui-particle-tone', particleTones[Math.floor(Math.random() * particleTones.length)])\n        particle.style.setProperty('--ui-particle-top', `${Math.random() * 100}%`)\n        container.appendChild(particle)\n      }\n    }\n  }\n\n  initParticles()\n  document.addEventListener('astro:after-swap', () => initParticles())\n</script>\n",
       "category": "Layout",
       "collections": [],
       "dependencies": [],
@@ -18923,7 +20574,7 @@
             }
           ],
           "propsExtends": "HTMLAttributes<'div'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  density?: 'low' | 'medium' | 'high'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  density = 'medium',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-particles'\n], classProp, className)\n---\n\n<div\n  aria-hidden=\"true\"\n  class:list={classList}\n  data-ui-particles={density}\n  {...passthrough}\n>\n  <slot />\n</div>\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  density?: 'low' | 'medium' | 'high'\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  density = 'medium',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-particles'\n], classProp, className)\n---\n\n<div\n  aria-hidden=\"true\"\n  class:list={classList}\n  data-ui-particles={density}\n  {...passthrough}\n>\n  <slot />\n</div>\n\n<script>\n  type ParticleDensity = 'low' | 'medium' | 'high'\n\n  const densityConfig: Record<ParticleDensity, number> = {\n    low: 15,\n    medium: 25,\n    high: 40\n  }\n\n  const particleTones = [\n    'var(--brand)',\n    'var(--accent)',\n    'var(--glow, var(--brand))'\n  ]\n\n  const initParticles = (scope: ParentNode = document) => {\n    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return\n\n    for (const container of scope.querySelectorAll<HTMLElement>('[data-ui-particles]')) {\n      if (container.hasAttribute('data-ui-particles-initialized')) continue\n\n      container.setAttribute('data-ui-particles-initialized', '')\n\n      const density = (container.dataset.uiParticles || 'medium') as ParticleDensity\n      const count = densityConfig[density]\n\n      for (let index = 0; index < count; index++) {\n        const particle = document.createElement('span')\n        const size = Math.random() * 12 + 8\n\n        particle.className = 'ui-particles__particle'\n        particle.style.setProperty('--ui-particle-delay', `${Math.random() * 8}s`)\n        particle.style.setProperty('--ui-particle-duration', `${20 + Math.random() * 15}s`)\n        particle.style.setProperty('--ui-particle-left', `${Math.random() * 100}%`)\n        particle.style.setProperty('--ui-particle-size', `${size}px`)\n        particle.style.setProperty('--ui-particle-tone', particleTones[Math.floor(Math.random() * particleTones.length)])\n        particle.style.setProperty('--ui-particle-top', `${Math.random() * 100}%`)\n        container.appendChild(particle)\n      }\n    }\n  }\n\n  initParticles()\n  document.addEventListener('astro:after-swap', () => initParticles())\n</script>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
@@ -18962,7 +20613,7 @@
             }
           ],
           "propsExtends": "ComponentPropsWithoutRef<'div'>",
-          "source": "export interface ParticlesProps extends ComponentPropsWithoutRef<'div'> {\n  density?: 'low' | 'medium' | 'high'\n}\n\nexport const Particles = ({ className, density = 'medium', ...props }: ParticlesProps) => (\n  <div aria-hidden=\"true\" className={composeClassName('ui-particles', className)} data-ui-particles={density} {...props} />\n)",
+          "source": "export interface ParticlesProps extends ComponentPropsWithoutRef<'div'> {\n  density?: 'low' | 'medium' | 'high'\n}\n\nexport const Particles = ({ children, className, density = 'medium', ...props }: ParticlesProps) => {\n  const [particles, setParticles] = useState<ParticleItem[]>([])\n\n  useEffect(() => {\n    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return\n\n    // Particle geometry is client-only to keep SSR output stable while retaining per-load variation.\n    // eslint-disable-next-line @eslint-react/set-state-in-effect\n    setParticles(createParticles(density))\n  }, [density])\n\n  return (\n    <div aria-hidden=\"true\" className={composeClassName('ui-particles', className)} data-ui-particles={density} {...props}>\n      {children}\n      {particles.map(particle => <span className=\"ui-particles__particle\" key={particle.id} style={particle.style} />)}\n    </div>\n  )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -19796,6 +21447,18 @@
     },
     {
       "apiReference": [
+        {
+          "attribute": "as",
+          "defaultValue": "\"div\"",
+          "description": "Changes the root element when the statistic is a standalone semantic region.",
+          "values": "\"article\" | \"div\" | \"section\""
+        },
+        {
+          "attribute": "variant",
+          "defaultValue": "\"default\"",
+          "description": "Changes the surface treatment while preserving the same metric structure.",
+          "values": "\"accent\" | \"default\" | \"glass\""
+        },
         {
           "attribute": "label",
           "defaultValue": "-",
@@ -19821,9 +21484,11 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  label?: string\n  value?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  label,\n  value,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-stat'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  {...passthrough}\n>\n  {label && <div class=\"ui-stat-label\">{label}</div>}\n  {value && <div class=\"ui-stat-value\">{value}</div>}\n  <slot />\n</div>\n\n",
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  as?: 'article' | 'div' | 'section'\n  class?: string | null\n  className?: string\n  label?: string\n  value?: string\n  variant?: 'accent' | 'default' | 'glass'\n}\n\nconst {\n  as: Tag = 'div',\n  class: classProp = '',\n  className = '',\n  label,\n  value,\n  variant = 'default',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-stat',\n  variant !== 'default' && `ui-stat--${variant}`\n], classProp, className)\n---\n\n<Tag\n  class:list={classList}\n  data-variant={variant}\n  {...passthrough}\n>\n  {label && <div class=\"ui-stat-label\">{label}</div>}\n  {value && <div class=\"ui-stat-value\">{value}</div>}\n  <slot />\n</Tag>\n",
       "category": "Data display",
-      "collections": [],
+      "collections": [
+        "Data visualization"
+      ],
       "dependencies": [],
       "description": "Pairs one prominent metric with a concise descriptive label.",
       "files": [
@@ -19833,11 +21498,16 @@
       "frameworkDetails": {
         "astro": {
           "available": true,
-          "example": "<Stat label=\"Active workspaces\" value=\"1,234\" />",
+          "example": "<Stat label=\"Active workspaces\" value=\"1,234\" variant=\"accent\" />",
           "importStatement": "import { Stat } from '@santi020k/lumen-astro'",
           "language": "astro",
           "packageName": "@santi020k/lumen-astro",
           "props": [
+            {
+              "name": "as",
+              "optional": true,
+              "type": "'article' | 'div' | 'section'"
+            },
             {
               "name": "class",
               "optional": true,
@@ -19857,14 +21527,21 @@
               "name": "value",
               "optional": true,
               "type": "string"
+            },
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "'accent' | 'default' | 'glass'"
             }
           ],
           "propsExtends": "HTMLAttributes<'div'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  label?: string\n  value?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  label,\n  value,\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-stat'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  {...passthrough}\n>\n  {label && <div class=\"ui-stat-label\">{label}</div>}\n  {value && <div class=\"ui-stat-value\">{value}</div>}\n  <slot />\n</div>\n\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  as?: 'article' | 'div' | 'section'\n  class?: string | null\n  className?: string\n  label?: string\n  value?: string\n  variant?: 'accent' | 'default' | 'glass'\n}\n\nconst {\n  as: Tag = 'div',\n  class: classProp = '',\n  className = '',\n  label,\n  value,\n  variant = 'default',\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-stat',\n  variant !== 'default' && `ui-stat--${variant}`\n], classProp, className)\n---\n\n<Tag\n  class:list={classList}\n  data-variant={variant}\n  {...passthrough}\n>\n  {label && <div class=\"ui-stat-label\">{label}</div>}\n  {value && <div class=\"ui-stat-value\">{value}</div>}\n  <slot />\n</Tag>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
           "attributes": [
+            "variant",
+            "as",
             "label",
             "value",
             "class, className",
@@ -19875,24 +21552,29 @@
             "mode": "registration",
             "setup": "Call defineLumenElements() once before rendering Lumen custom elements."
           },
-          "example": "<lumen-stat label=\"Active workspaces\" value=\"1,234\"></lumen-stat>",
+          "example": "<lumen-stat label=\"Active workspaces\" value=\"1,234\" variant=\"accent\"></lumen-stat>",
           "importStatement": "import { defineLumenElements } from '@santi020k/lumen-elements/define'",
           "language": "html",
           "packageName": "@santi020k/lumen-elements",
           "props": [],
           "propsExtends": "HTMLElement attributes",
           "registration": "defineLumenElements()",
-          "source": "Stat: { baseClassName: 'ui-stat', tagName: 'lumen-stat' }",
+          "source": "Stat: {\n    attributeClasses: {\n      variant: {\n        accent: 'ui-stat--accent',\n        glass: 'ui-stat--glass'\n      }\n    },\n    baseClassName: 'ui-stat',\n    defaults: { variant: 'default' },\n    tagName: 'lumen-stat'\n  }",
           "styleImport": "import '@santi020k/lumen-elements/styles.css'",
           "tagName": "lumen-stat"
         },
         "react": {
           "available": true,
-          "example": "<Stat label=\"Active workspaces\" value=\"1,234\" />",
+          "example": "<Stat label=\"Active workspaces\" value=\"1,234\" variant=\"accent\" />",
           "importStatement": "import { Stat } from '@santi020k/lumen-react'",
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
           "props": [
+            {
+              "name": "as",
+              "optional": true,
+              "type": "T"
+            },
             {
               "name": "label",
               "optional": true,
@@ -19902,10 +21584,15 @@
               "name": "value",
               "optional": true,
               "type": "string"
+            },
+            {
+              "name": "variant",
+              "optional": true,
+              "type": "'accent' | 'default' | 'glass'"
             }
           ],
-          "propsExtends": "ComponentPropsWithoutRef<'div'>",
-          "source": "export interface StatProps extends ComponentPropsWithoutRef<'div'> {\n  label?: string\n  value?: string\n}\n\nexport const Stat = ({ className, label, value, children, ...props }: StatProps) => (\n  <div className={composeClassName('ui-stat', className)} {...props}>\n    {label && <div className=\"ui-stat-label\">{label}</div>}\n    {value && <div className=\"ui-stat-value\">{value}</div>}\n    {children}\n  </div>\n)",
+          "propsExtends": "PrimitiveProps",
+          "source": "export type StatProps<T extends ElementType = 'div'> = PrimitiveProps & {\n  as?: T\n  label?: string\n  value?: string\n  variant?: 'accent' | 'default' | 'glass'\n}\n\nexport const Stat = <T extends ElementType = 'div'>({\n  as,\n  className,\n  label,\n  value,\n  variant = 'default',\n  children,\n  ...props\n}: StatProps<T>) => (\n  <Primitive\n    {...(as ? { as } : {})}\n    className={composeClassName(variant !== 'default' && `ui-stat--${variant}`, className)}\n    data-variant={variant}\n    {...props}\n    uiClassName=\"ui-stat\"\n  >\n    {label && <div className=\"ui-stat-label\">{label}</div>}\n    {value && <div className=\"ui-stat-value\">{value}</div>}\n    {children}\n  </Primitive>\n)",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -19916,42 +21603,74 @@
       },
       "guidance": {
         "when": "Use to pair one prominent metric with its concise label.",
-        "distinction": "Use Chart when the trend or relationship matters, or Descriptions for several equally weighted key–value facts."
+        "distinction": "Use as=\"article\" when the metric and its supporting content stand alone. Use variant=\"accent\" for a featured metric and variant=\"glass\" on a selective translucent surface. Use Chart when the trend or relationship matters, or Descriptions for several equally weighted key–value facts."
       },
       "kebab": "stat",
       "keyboardInteractions": [],
       "keywords": [
+        "accent",
+        "alone",
+        "and",
+        "article",
+        "breakdowns",
+        "categorical",
         "chart",
+        "compact",
+        "comparisons",
         "concise",
+        "content",
+        "custom",
         "data",
         "descriptions",
         "descriptive",
         "display",
         "equally",
         "facts",
+        "featured",
         "for",
+        "glass",
         "its",
         "key",
         "label",
+        "match",
         "matters",
         "metric",
+        "metrics",
         "one",
+        "ordered",
         "pair",
         "pairs",
+        "part",
+        "plots",
         "prominent",
+        "question",
         "relationship",
+        "selective",
         "several",
+        "stand",
         "stat",
+        "supporting",
+        "surface",
         "the",
+        "translucent",
         "trend",
+        "trends",
         "use",
         "value",
+        "variant",
+        "visualization",
         "weighted",
         "when",
+        "whole",
         "with"
       ],
       "name": "Stat",
       "props": [
+        {
+          "name": "as",
+          "optional": true,
+          "type": "'article' | 'div' | 'section'"
+        },
         {
           "name": "class",
           "optional": true,
@@ -19971,10 +21690,20 @@
           "name": "value",
           "optional": true,
           "type": "string"
+        },
+        {
+          "name": "variant",
+          "optional": true,
+          "type": "'accent' | 'default' | 'glass'"
         }
       ],
       "propsExtends": "HTMLAttributes<'div'>",
-      "recipes": [],
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
+        }
+      ],
       "runtimeEvents": []
     },
     {
@@ -20012,7 +21741,9 @@
       ],
       "astroSource": "---\nimport type { HTMLAttributes } from 'astro/types'\nimport { composeClassName } from '@santi020k/lumen-core'\n\nexport interface Props extends HTMLAttributes<'meter'> {\n  value: number\n  min?: number\n  max?: number\n  low?: number\n  high?: number\n  optimum?: number\n}\n\nconst {\n  class: className,\n  value,\n  min = 0,\n  max = 100,\n  ...props\n} = Astro.props\n---\n\n<meter\n  class={composeClassName('ui-meter', className)}\n  value={value}\n  min={min}\n  max={max}\n  {...props}\n>\n  <slot>{value}</slot>\n</meter>\n",
       "category": "Data display",
-      "collections": [],
+      "collections": [
+        "Data visualization"
+      ],
       "dependencies": [],
       "description": "Displays a scalar value within a known range.",
       "files": [
@@ -20111,18 +21842,30 @@
       "keyboardInteractions": [],
       "keywords": [
         "advancing",
+        "and",
+        "breakdowns",
+        "categorical",
+        "compact",
+        "comparisons",
         "completion",
         "current",
+        "custom",
         "data",
         "display",
         "displays",
         "for",
         "known",
+        "match",
         "measurement",
         "meter",
+        "metrics",
         "not",
+        "ordered",
+        "part",
+        "plots",
         "progress",
         "quantity",
+        "question",
         "range",
         "represents",
         "scalar",
@@ -20132,9 +21875,13 @@
         "storage",
         "such",
         "task",
+        "the",
         "toward",
+        "trends",
         "use",
         "value",
+        "visualization",
+        "whole",
         "within",
         "work"
       ],
@@ -20172,7 +21919,12 @@
         }
       ],
       "propsExtends": "HTMLAttributes<'meter'>",
-      "recipes": [],
+      "recipes": [
+        {
+          "name": "data-visualization",
+          "type": "recipe"
+        }
+      ],
       "runtimeEvents": []
     },
     {
@@ -22295,8 +24047,8 @@
         {
           "attribute": "items",
           "defaultValue": "[]",
-          "description": "Defines the in-page navigation targets and labels.",
-          "values": "Array<{ href, label }>"
+          "description": "Defines the in-page navigation targets, labels, and optional heading depth from 1 through 6.",
+          "values": "Array<{ href, label, depth? }>"
         },
         {
           "attribute": "class, className",
@@ -22311,7 +24063,7 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype AnchorLink = { href: string; label: string }\n\nexport interface Props extends HTMLAttributes<'nav'> {\n  class?: string | null\n  className?: string\n  items?: AnchorLink[]\n}\n\nconst {\n  'aria-label': ariaLabel = 'On this page',\n  class: classProp = '',\n  className = '',\n  items = [],\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-anchor'\n], classProp, className)\n---\n\n<nav\n  aria-label={ariaLabel}\n  class:list={classList}\n  data-ui-anchor\n  {...passthrough}\n>\n  {items.length > 0 && (\n    <ol>\n      {items.map((item, index) => (\n        <li>\n          <a data-active={index === 0 ? 'true' : 'false'} href={item.href}>{item.label}</a>\n        </li>\n      ))}\n    </ol>\n  )}\n  <slot />\n</nav>\n",
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype AnchorDepth = 1 | 2 | 3 | 4 | 5 | 6\n\ntype AnchorLink = {\n  depth?: AnchorDepth\n  href: string\n  label: string\n}\n\nexport interface Props extends HTMLAttributes<'nav'> {\n  class?: string | null\n  className?: string\n  items?: AnchorLink[]\n}\n\nconst {\n  'aria-label': ariaLabel = 'On this page',\n  class: classProp = '',\n  className = '',\n  items = [],\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-anchor'\n], classProp, className)\n---\n\n<nav\n  aria-label={ariaLabel}\n  class:list={classList}\n  data-ui-anchor\n  {...passthrough}\n>\n  {items.length > 0 && (\n    <ol>\n      {items.map((item, index) => (\n        <li>\n          <a\n            data-active={index === 0 ? 'true' : 'false'}\n            data-depth={item.depth}\n            href={item.href}\n          >\n            {item.label}\n          </a>\n        </li>\n      ))}\n    </ol>\n  )}\n  <slot />\n</nav>\n",
       "category": "Navigation",
       "collections": [
         "Disclosure and navigation"
@@ -22325,7 +24077,7 @@
       "frameworkDetails": {
         "astro": {
           "available": true,
-          "example": "<Anchor items={[{ href: \"#installation\", label: \"Installation\" }, { href: \"#usage\", label: \"Usage\" }]} />",
+          "example": "<Anchor items={[{ href: \"#installation\", label: \"Installation\", depth: 2 }, { href: \"#usage\", label: \"Usage\", depth: 3 }]} />",
           "importStatement": "import { Anchor } from '@santi020k/lumen-astro'",
           "language": "astro",
           "packageName": "@santi020k/lumen-astro",
@@ -22347,7 +24099,7 @@
             }
           ],
           "propsExtends": "HTMLAttributes<'nav'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype AnchorLink = { href: string; label: string }\n\nexport interface Props extends HTMLAttributes<'nav'> {\n  class?: string | null\n  className?: string\n  items?: AnchorLink[]\n}\n\nconst {\n  'aria-label': ariaLabel = 'On this page',\n  class: classProp = '',\n  className = '',\n  items = [],\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-anchor'\n], classProp, className)\n---\n\n<nav\n  aria-label={ariaLabel}\n  class:list={classList}\n  data-ui-anchor\n  {...passthrough}\n>\n  {items.length > 0 && (\n    <ol>\n      {items.map((item, index) => (\n        <li>\n          <a data-active={index === 0 ? 'true' : 'false'} href={item.href}>{item.label}</a>\n        </li>\n      ))}\n    </ol>\n  )}\n  <slot />\n</nav>\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ntype AnchorDepth = 1 | 2 | 3 | 4 | 5 | 6\n\ntype AnchorLink = {\n  depth?: AnchorDepth\n  href: string\n  label: string\n}\n\nexport interface Props extends HTMLAttributes<'nav'> {\n  class?: string | null\n  className?: string\n  items?: AnchorLink[]\n}\n\nconst {\n  'aria-label': ariaLabel = 'On this page',\n  class: classProp = '',\n  className = '',\n  items = [],\n  ...rest\n} = Astro.props\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-anchor'\n], classProp, className)\n---\n\n<nav\n  aria-label={ariaLabel}\n  class:list={classList}\n  data-ui-anchor\n  {...passthrough}\n>\n  {items.length > 0 && (\n    <ol>\n      {items.map((item, index) => (\n        <li>\n          <a\n            data-active={index === 0 ? 'true' : 'false'}\n            data-depth={item.depth}\n            href={item.href}\n          >\n            {item.label}\n          </a>\n        </li>\n      ))}\n    </ol>\n  )}\n  <slot />\n</nav>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
@@ -22376,7 +24128,7 @@
         },
         "react": {
           "available": true,
-          "example": "<Anchor items={[{ href: \"#installation\", label: \"Installation\" }, { href: \"#usage\", label: \"Usage\" }]} />",
+          "example": "<Anchor items={[{ href: \"#installation\", label: \"Installation\", depth: 2 }, { href: \"#usage\", label: \"Usage\", depth: 3 }]} />",
           "importStatement": "import { Anchor } from '@santi020k/lumen-react'",
           "language": "tsx",
           "packageName": "@santi020k/lumen-react",
@@ -22388,7 +24140,7 @@
             }
           ],
           "propsExtends": "ComponentPropsWithoutRef<'nav'>",
-          "source": "export interface AnchorProps extends ComponentPropsWithoutRef<'nav'> {\n  items?: AnchorLink[]\n}\n\nexport const Anchor = ({ 'aria-label': ariaLabel = 'On this page', children, className, items = emptyAnchorLinks, ...props }: AnchorProps) => (\n  <nav aria-label={ariaLabel} className={composeClassName('ui-anchor', className)} data-ui-anchor {...props}>\n    {items.length > 0 && (\n      <ol>\n        {items.map((item, index) => (\n          <li key={item.href}>\n            <a data-active={index === 0 ? 'true' : 'false'} href={item.href}>{item.label}</a>\n          </li>\n        ))}\n      </ol>\n    )}\n    {children}\n  </nav>\n)",
+          "source": "export interface AnchorProps extends ComponentPropsWithoutRef<'nav'> {\n  items?: AnchorLink[]\n}\n\nexport const Anchor = ({ 'aria-label': ariaLabel = 'On this page', children, className, items = emptyAnchorLinks, ...props }: AnchorProps) => (\n  <nav aria-label={ariaLabel} className={composeClassName('ui-anchor', className)} data-ui-anchor {...props}>\n    {items.length > 0 && (\n      <ol>\n        {items.map((item, index) => (\n          <li key={item.href}>\n            <a\n              data-active={index === 0 ? 'true' : 'false'}\n              data-depth={item.depth}\n              href={item.href}\n            >\n              {item.label}\n            </a>\n          </li>\n        ))}\n      </ol>\n    )}\n    {children}\n  </nav>\n)",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -24287,7 +26039,7 @@
           "values": "HTML attributes"
         }
       ],
-      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  content?: string\n  gap?: number\n  rotate?: number\n  text?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  content,\n  gap = 120,\n  rotate = -22,\n  text = 'Confidential',\n  ...rest\n} = Astro.props\n\nconst watermarkText = content ?? text\nconst tileSize = Math.max(1, gap)\nconst watermarkXmlEntities: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&apos;'\n}\nconst escapedWatermarkText = watermarkText.replaceAll(\n  /[&<>\"']/g,\n  character => watermarkXmlEntities[character] ?? character\n)\nconst watermarkSvg = [\n  `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${tileSize}\" height=\"${tileSize}\" viewBox=\"0 0 ${tileSize} ${tileSize}\">`,\n  `<text x=\"${tileSize / 2}\" y=\"${tileSize / 2}\" dominant-baseline=\"middle\" text-anchor=\"middle\"`,\n  ` transform=\"rotate(${rotate} ${tileSize / 2} ${tileSize / 2})\"`,\n  ' fill=\"black\" font-family=\"system-ui, sans-serif\" font-size=\"16\" font-weight=\"500\" letter-spacing=\"1.6\">',\n  `${escapedWatermarkText}</text></svg>`\n].join('')\nconst watermarkImage = `url(\"data:image/svg+xml,${encodeURIComponent(watermarkSvg)}\")`\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-watermark'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  data-ui-watermark\n  style={`--ui-watermark-gap:${tileSize}px;--ui-watermark-image:${watermarkImage}`}\n  {...passthrough}\n>\n  <slot />\n  <div aria-hidden=\"true\" class=\"ui-watermark__overlay\" data-text={watermarkText}></div>\n</div>\n",
+      "astroSource": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  content?: string\n  gap?: number\n  rotate?: number\n  text?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  content,\n  gap = 120,\n  rotate = -22,\n  text = 'Confidential',\n  ...rest\n} = Astro.props\n\nconst watermarkText = content ?? text\nconst tileSize = Math.max(1, gap)\nconst watermarkXmlEntities: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&apos;'\n}\nconst escapedWatermarkText = watermarkText.replaceAll(\n  /[&<>\"']/g,\n  character => watermarkXmlEntities[character] ?? character\n)\nconst watermarkSvg = [\n  `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${tileSize}\" height=\"${tileSize}\" viewBox=\"0 0 ${tileSize} ${tileSize}\">`,\n  `<text x=\"${tileSize / 2}\" y=\"${tileSize / 2}\" dominant-baseline=\"middle\" text-anchor=\"middle\"`,\n  ` transform=\"rotate(${rotate} ${tileSize / 2} ${tileSize / 2})\"`,\n  ' fill=\"black\" font-family=\"Montserrat, Avenir Next, Segoe UI, sans-serif\" font-size=\"16\" font-weight=\"500\" letter-spacing=\"1.6\">',\n  `${escapedWatermarkText}</text></svg>`\n].join('')\nconst watermarkImage = `url(\"data:image/svg+xml,${encodeURIComponent(watermarkSvg)}\")`\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-watermark'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  data-ui-watermark\n  style={`--ui-watermark-gap:${tileSize}px;--ui-watermark-image:${watermarkImage}`}\n  {...passthrough}\n>\n  <slot />\n  <div aria-hidden=\"true\" class=\"ui-watermark__overlay\" data-text={watermarkText}></div>\n</div>\n",
       "category": "Layout",
       "collections": [],
       "dependencies": [],
@@ -24336,7 +26088,7 @@
             }
           ],
           "propsExtends": "HTMLAttributes<'div'>",
-          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  content?: string\n  gap?: number\n  rotate?: number\n  text?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  content,\n  gap = 120,\n  rotate = -22,\n  text = 'Confidential',\n  ...rest\n} = Astro.props\n\nconst watermarkText = content ?? text\nconst tileSize = Math.max(1, gap)\nconst watermarkXmlEntities: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&apos;'\n}\nconst escapedWatermarkText = watermarkText.replaceAll(\n  /[&<>\"']/g,\n  character => watermarkXmlEntities[character] ?? character\n)\nconst watermarkSvg = [\n  `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${tileSize}\" height=\"${tileSize}\" viewBox=\"0 0 ${tileSize} ${tileSize}\">`,\n  `<text x=\"${tileSize / 2}\" y=\"${tileSize / 2}\" dominant-baseline=\"middle\" text-anchor=\"middle\"`,\n  ` transform=\"rotate(${rotate} ${tileSize / 2} ${tileSize / 2})\"`,\n  ' fill=\"black\" font-family=\"system-ui, sans-serif\" font-size=\"16\" font-weight=\"500\" letter-spacing=\"1.6\">',\n  `${escapedWatermarkText}</text></svg>`\n].join('')\nconst watermarkImage = `url(\"data:image/svg+xml,${encodeURIComponent(watermarkSvg)}\")`\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-watermark'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  data-ui-watermark\n  style={`--ui-watermark-gap:${tileSize}px;--ui-watermark-image:${watermarkImage}`}\n  {...passthrough}\n>\n  <slot />\n  <div aria-hidden=\"true\" class=\"ui-watermark__overlay\" data-text={watermarkText}></div>\n</div>\n",
+          "source": "---\nimport { resolveLumenAstroProps } from '@santi020k/lumen-core'\n\nimport type { HTMLAttributes } from 'astro/types'\n\ninterface Props extends HTMLAttributes<'div'> {\n  class?: string | null\n  className?: string\n  content?: string\n  gap?: number\n  rotate?: number\n  text?: string\n}\n\nconst {\n  class: classProp = '',\n  className = '',\n  content,\n  gap = 120,\n  rotate = -22,\n  text = 'Confidential',\n  ...rest\n} = Astro.props\n\nconst watermarkText = content ?? text\nconst tileSize = Math.max(1, gap)\nconst watermarkXmlEntities: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&apos;'\n}\nconst escapedWatermarkText = watermarkText.replaceAll(\n  /[&<>\"']/g,\n  character => watermarkXmlEntities[character] ?? character\n)\nconst watermarkSvg = [\n  `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${tileSize}\" height=\"${tileSize}\" viewBox=\"0 0 ${tileSize} ${tileSize}\">`,\n  `<text x=\"${tileSize / 2}\" y=\"${tileSize / 2}\" dominant-baseline=\"middle\" text-anchor=\"middle\"`,\n  ` transform=\"rotate(${rotate} ${tileSize / 2} ${tileSize / 2})\"`,\n  ' fill=\"black\" font-family=\"Montserrat, Avenir Next, Segoe UI, sans-serif\" font-size=\"16\" font-weight=\"500\" letter-spacing=\"1.6\">',\n  `${escapedWatermarkText}</text></svg>`\n].join('')\nconst watermarkImage = `url(\"data:image/svg+xml,${encodeURIComponent(watermarkSvg)}\")`\n\nconst { classList, passthrough } = resolveLumenAstroProps(rest, [\n  'ui-watermark'\n], classProp, className)\n---\n\n<div\n  class:list={classList}\n  data-ui-watermark\n  style={`--ui-watermark-gap:${tileSize}px;--ui-watermark-image:${watermarkImage}`}\n  {...passthrough}\n>\n  <slot />\n  <div aria-hidden=\"true\" class=\"ui-watermark__overlay\" data-text={watermarkText}></div>\n</div>\n",
           "styleImport": "import '@santi020k/lumen-astro/styles.css'"
         },
         "elements": {
@@ -24393,7 +26145,7 @@
             }
           ],
           "propsExtends": "ComponentPropsWithoutRef<'div'>",
-          "source": "export interface WatermarkProps extends ComponentPropsWithoutRef<'div'> {\n  content?: string\n  gap?: number\n  rotate?: number\n  text?: string\n}\n\nexport const Watermark = ({ children, className, content, gap = 120, rotate = -22, style, text = 'Confidential', ...props }: WatermarkProps) => {\n  const watermarkText = content ?? text\n  const tileSize = Math.max(1, gap)\n\n  const watermarkXmlEntities: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&apos;'\n  }\n\n  const escapedWatermarkText = watermarkText.replaceAll(\n    /[&<>\"']/g,\n    character => watermarkXmlEntities[character] ?? character\n  )\n\n  const watermarkSvg = [\n    `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${tileSize}\" height=\"${tileSize}\" viewBox=\"0 0 ${tileSize} ${tileSize}\">`,\n    `<text x=\"${tileSize / 2}\" y=\"${tileSize / 2}\" dominant-baseline=\"middle\" text-anchor=\"middle\"`,\n    ` transform=\"rotate(${rotate} ${tileSize / 2} ${tileSize / 2})\"`,\n    ' fill=\"black\" font-family=\"system-ui, sans-serif\" font-size=\"16\" font-weight=\"500\" letter-spacing=\"1.6\">',\n    `${escapedWatermarkText}</text></svg>`\n  ].join('')\n\n  const watermarkImage = `url(\"data:image/svg+xml,${encodeURIComponent(watermarkSvg)}\")`\n\n  return (\n    <div\n      className={composeClassName('ui-watermark', className)}\n      data-ui-watermark\n      style={{\n        ['--ui-watermark-gap' as string]: `${tileSize}px`,\n        ['--ui-watermark-image' as string]: watermarkImage,\n        ...style\n      }}\n      {...props}\n    >\n      {children}\n      <div aria-hidden=\"true\" className=\"ui-watermark__overlay\" data-text={watermarkText} />\n    </div>\n  )\n}",
+          "source": "export interface WatermarkProps extends ComponentPropsWithoutRef<'div'> {\n  content?: string\n  gap?: number\n  rotate?: number\n  text?: string\n}\n\nexport const Watermark = ({ children, className, content, gap = 120, rotate = -22, style, text = 'Confidential', ...props }: WatermarkProps) => {\n  const watermarkText = content ?? text\n  const tileSize = Math.max(1, gap)\n\n  const watermarkXmlEntities: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&apos;'\n  }\n\n  const escapedWatermarkText = watermarkText.replaceAll(\n    /[&<>\"']/g,\n    character => watermarkXmlEntities[character] ?? character\n  )\n\n  const watermarkSvg = [\n    `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${tileSize}\" height=\"${tileSize}\" viewBox=\"0 0 ${tileSize} ${tileSize}\">`,\n    `<text x=\"${tileSize / 2}\" y=\"${tileSize / 2}\" dominant-baseline=\"middle\" text-anchor=\"middle\"`,\n    ` transform=\"rotate(${rotate} ${tileSize / 2} ${tileSize / 2})\"`,\n    ' fill=\"black\" font-family=\"Montserrat, Avenir Next, Segoe UI, sans-serif\" font-size=\"16\" font-weight=\"500\" letter-spacing=\"1.6\">',\n    `${escapedWatermarkText}</text></svg>`\n  ].join('')\n\n  const watermarkImage = `url(\"data:image/svg+xml,${encodeURIComponent(watermarkSvg)}\")`\n\n  return (\n    <div\n      className={composeClassName('ui-watermark', className)}\n      data-ui-watermark\n      style={{\n        ['--ui-watermark-gap' as string]: `${tileSize}px`,\n        ['--ui-watermark-image' as string]: watermarkImage,\n        ...style\n      }}\n      {...props}\n    >\n      {children}\n      <div aria-hidden=\"true\" className=\"ui-watermark__overlay\" data-text={watermarkText} />\n    </div>\n  )\n}",
           "styleImport": "import '@santi020k/lumen-react/styles.css'"
         }
       },
@@ -24890,12 +26642,12 @@
     }
   ],
   "docs": {
-    "aiUsage": "# AI Usage Guide\n\nUse this guide when an AI agent is building an app with Lumen or updating examples that teach\nanother agent how to use the library.\n\n## Install the Lumen Agent Skill\n\nLumen ships a portable Agent Skill for AI coding tools that support the open `SKILL.md` format:\n\n```bash\nnpx skills add santi020k/lumen --skill lumen-ui\n```\n\nThe source lives in [`skills/lumen-ui`](../skills/lumen-ui). The skill provides the durable\nframework-selection, component-composition, theming, accessibility, and verification workflow.\nUse it by naming `$lumen-ui` in a prompt, or let a compatible agent trigger it from Lumen-specific\nrequests.\n\nThe skill and MCP server complement each other: the skill explains how to work, while\n`@santi020k/lumen-mcp` supplies structured catalog search, framework-specific contracts, recipes,\nsource, tokens, resources, and rules.\n\n## Pick the Right Package\n\nUse the framework requested by the user. Every adapter shares the same Lumen foundation.\n\n| App Target | Install | Import Components From | Load Styles From |\n| --- | --- | --- | --- |\n| Astro | `@santi020k/lumen-astro` | `@santi020k/lumen-astro` | `@santi020k/lumen-astro/styles.css` |\n| React | `@santi020k/lumen-react` | `@santi020k/lumen-react` | `@santi020k/lumen-react/styles.css` |\n| Web Components | `@santi020k/lumen-elements` | `@santi020k/lumen-elements/define` | `@santi020k/lumen-elements/styles.css` |\n| Package metadata | `@santi020k/lumen-core` | `@santi020k/lumen-core` | Not applicable |\n\nEach framework package includes the shared foundation. Install `@santi020k/lumen` separately only\nwhen you need its framework-neutral CLI or registry metadata.\n\n## MCP-Assisted Workflow\n\nConnect `@santi020k/lumen-mcp` when the agent supports Model Context Protocol. The server returns\nvalidated structured content as well as readable text, so agents can select components without\nscraping documentation.\n\n```bash\ncodex mcp add lumen -- npx -y @santi020k/lumen-mcp\n```\n\nFor Codex project configuration:\n\n```toml\n[mcp_servers.lumen]\nenabled = true\ncommand = \"npx\"\nargs = [\"-y\", \"@santi020k/lumen-mcp\"]\n```\n\nUse this sequence:\n\n1. Read `lumen://meta` and `lumen://diagnostics` to identify and verify the snapshot.\n2. Read `lumen://rules`.\n3. Search for the use case with `lumen_search`, passing the target `framework` when known.\n4. Inspect the selected framework with `lumen_get_component` and `detail: \"usage\"`.\n5. Follow its framework behavior setup and hook/controller contract.\n6. Read related multi-component guidance with `lumen_get_recipe`.\n7. Request `detail: \"source\"` only when the usage contract is insufficient.\n8. Read `lumen://tokens` before introducing custom styling.\n9. Retain `lumen://catalog-manifest` and use `lumen_diff_catalog` after upgrades to identify contracts that need refreshing.\n\nExample framework-aware component request:\n\n```json\n{\n  \"name\": \"lumen_get_component\",\n  \"arguments\": {\n    \"name\": \"DateRangePicker\",\n    \"framework\": \"react\",\n    \"detail\": \"usage\"\n  }\n}\n```\n\nStable resources are available at `lumen://rules`, `lumen://tokens`, `lumen://components`,\n`lumen://meta`, `lumen://catalog-manifest`, `lumen://diagnostics`,\n`lumen://components/{name}`, and `lumen://recipes/{name}`. See\n[`packages/mcp/README.md`](../packages/mcp/README.md) for Claude Desktop, Cursor, generic stdio,\nlocal repository, and programmatic examples.\n\n## Minimal Setup\n\nImport the stylesheet once in the app's global CSS, root layout, or app entry.\n\n```css\n@import \"@santi020k/lumen-react/styles.css\";\n```\n\nIf Tailwind is present, keep both imports in the same shared CSS entry.\n\n```css\n@import \"@santi020k/lumen-react/layers.css\";\n@import \"tailwindcss\";\n@import \"@santi020k/lumen-react/styles.css\";\n```\n\nKeep the layer prelude first. It places Tailwind base styles below Lumen components and Tailwind\nutilities above them, so consumer spacing, display, radius, width, and responsive visibility\nclasses override Lumen defaults predictably.\n\nAstro apps should mount `UIPrimitives` once in the root layout when using interactive primitives\nsuch as dialogs, menus, popovers, tabs, carousels, command lists, toggles, validated forms, or\ntoasts. Do not place `UIPrimitives` in each component example or next to each primitive instance;\none root include enhances all matching `data-ui-*` markup on the page.\n\n```astro\n---\nimport { UIPrimitives } from '@santi020k/lumen-astro'\n---\n\n<UIPrimitives />\n```\n\n## Astro\n\nUse direct named imports from `@santi020k/lumen-astro`.\n\n```astro\n---\nimport { Button, Card, Input, Label } from '@santi020k/lumen-astro'\n---\n\n<Card>\n  <Label for=\"email\">Email</Label>\n  <Input id=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n  <Button type=\"submit\">Subscribe</Button>\n</Card>\n```\n\n## React\n\nReact components share the same visual classes and data attributes as Astro components. For\nbehavior-heavy primitives, use the React behavior hooks from `@santi020k/lumen-react` (`useDialog`,\n`usePopover`, `useDropdownMenu`, `useTabs`, `useSelect`, `useToast`, and `useTooltip`), which track\nthe Astro runtime's ARIA, keyboard, Escape, dismissal, and toast controller semantics.\n\nThe React package entry is a client boundary. In Next.js, it can be imported by a Server Component\nwithout evaluating Lumen's contexts and hooks in the React server runtime; the rendered Lumen\nsubtree becomes a Client Component boundary. Vite and other client-rendered React applications use\nthe same entry without additional setup.\n`Button`, `Link`, `ButtonLink`, and `Input` accept React 19 DOM refs directly as props.\n`Button asChild` composes the button contract onto one child element, while `Input visualSize` controls\npresentation without shadowing the native numeric `size` attribute.\n\n```tsx\nimport '@santi020k/lumen-react/styles.css'\nimport { Button, Card, Input, Label } from '@santi020k/lumen-react'\n\nexport function SubscribeForm() {\n  return (\n    <Card>\n      <Label htmlFor=\"email\">Email</Label>\n      <Input id=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n      <Button type=\"submit\">Subscribe</Button>\n    </Card>\n  )\n}\n```\n\n## Web Components\n\nRegister custom elements once, then use `lumen-*` tags in HTML. The elements adapter includes\ninteractive behavior parity for DataTable, Dialog, Popover, DropdownMenu, ContextMenu, Tabs,\nSelect, ThemeBuilder, Toast, Tooltip, forms, RichTextEditor, Schedule, and VirtualList: selection,\nvalidation, rich text command, context menu, schedule drag/drop, theme, and range events, ARIA\nstate, roving/listbox keyboard paths, Escape/outside dismissal, focus return/trapping, native\nselect form participation, and the same toast controller events as the Astro runtime.\n\n```html\n<script type=\"module\">\n  import { defineLumenElements } from '@santi020k/lumen-elements/define'\n\n  defineLumenElements()\n</script>\n\n<lumen-card>\n  <label for=\"email\">Email</label>\n  <lumen-input id=\"email\" type=\"email\" placeholder=\"you@example.com\"></lumen-input>\n  <lumen-button type=\"submit\">Subscribe</lumen-button>\n</lumen-card>\n```\n\n## Component Selection\n\nThe shared catalog includes:\n\n`Accordion`, `Alert`, `AlertDialog`, `Agenda`, `AspectRatio`, `Attachment`, `Autocomplete`,\n`Avatar`, `Badge`, `Breadcrumb`, `Bubble`, `Button`, `ButtonGroup`, `Calendar`, `Card`,\n`Carousel`, `Chart`, `Checkbox`, `Collapsible`, `Code`, `Combobox`, `Command`, `ColorPicker`,\n`ContextMenu`, `DataTable`, `DatePicker`, `DateRangePicker`, `Dialog`, `Direction`, `Drawer`,\n`DropdownMenu`, `Empty`, `Field`, `HoverCard`, `Icon`, `Input`, `InputGroup`, `InputOTP`, `Item`, `Kbd`,\n`Label`, `Marker`, `Menubar`, `Message`, `MessageScroller`, `NativeSelect`, `NavigationMenu`,\n`NumberField`, `Pagination`, `Popover`, `Progress`, `RadioGroup`, `Resizable`, `RichTextEditor`,\n`ScrollArea`, `Schedule`, `SearchField`, `Select`, `Separator`, `Sheet`, `Sidebar`, `Skeleton`,\n`Slider`, `Spinner`, `Switch`, `Table`, `Tabs`, `TagGroup`, `Textarea`, `ThemeBuilder`,\n`TimeField`, `Toast`, `Toggle`, `ToggleGroup`, `Tooltip`, `Tree`, `TreeGrid`, `Typography`, and\n`VirtualList`.\n\n## Product Recipes\n\n- Use `Icon name=\"search\"` or any Lucide icon name for standard interface pictograms. Kebab-case\n  names and Lucide aliases work. Pair decorative icons with `decorative`, and pass `label` only\n  when the icon carries meaning on its own. Lucide does not include brand marks such as GitHub;\n  render a project-owned SVG through the default `Icon` slot for brand and custom icons. Astro\n  reports unknown named icons during development instead of failing silently.\n- Use `Schedule` with `Agenda`, `Calendar`, and `DatePicker` for booking, CRM, content calendar, and\n  event planning screens. Mark slots with `data-ui-schedule-slot` and events with\n  `data-ui-schedule-event`; the runtime emits `ui:schedule-change` when a draggable event is moved.\n  `Calendar` renders a hidden input plus selectable date grid; Astro `UIPrimitives` and registered\n  Web Components wire month navigation and roving keyboard focus directly, while React apps can use\n  the `Calendar` component or `useCalendar` for the same date selection contract.\n  Astro `UIPrimitives` and registered Web Components bind schedule drag/drop directly; React apps\n  can use `useSchedule` for `rootProps`, `getEventProps`, `getSlotProps`, and `ui:schedule-change`\n  parity. Use `createScheduleSlots`, `moveScheduleEvent`, and `expandRecurringScheduleEvent` from\n  `@santi020k/lumen-core` for reusable schedule state; use `getScheduleConflicts` and\n  `canPlaceScheduleEvent` before committing drag/drop changes. Persist local schedule edits with\n  `createScheduleStorageKey`, `saveScheduleEvents`, and `loadScheduleEvents` against any\n  `localStorage`-compatible adapter. Use `resizeScheduleEvent` and `resizeScheduleEvents` for\n  snap-to-grid resize handles.\n- Use `DataTable`, `Tree`, `TreeGrid`, `VirtualList`, `Pagination`, and `Command` for dense data\n  collection workflows. Astro and Elements wire selectable/sortable `DataTable` behavior and\n  `VirtualList` range events; React emits the same data attributes for app-level adapters. `Tree`\n  and `TreeGrid` use roving keyboard focus, and `VirtualList` emits `ui:virtual-list-range` as the\n  rendered range changes. Use `createDataViewState`,\n  `serializeDataViewState`, `parseDataViewState`, `applyDataViewState`, and `getVirtualRange` for\n  saved views, filtering, sorting, pagination, and virtualization math. Use\n  `createDataViewStorageKey`, `saveDataViewState`, and `loadDataViewState` when saved views should\n  survive navigation or reloads. Use `pinDataViewColumn`, `unpinDataViewColumn`,\n  `toggleDataViewSelection`, `createDataViewSearchParams`, and `createDataViewServerRequest` when\n  connecting dense views to router state or server-backed data.\n- Use `Resizable` for split-pane editors, dashboards, inspectors, and side-by-side review layouts.\n  Astro `UIPrimitives` and registered Web Components generate separator handles and pane sizing\n  directly; React apps can use the `Resizable` component or `useResizable` for pointer, keyboard,\n  min/max, and double-click reset parity.\n- Use `ThemeBuilder`, `ColorPicker`, `Card`, `Button`, and `Input` to build token preview and export\n  tools. Add `data-ui-theme-brand-hue`, `data-ui-theme-accent-hue`, `data-ui-theme-scheme`,\n  `data-ui-theme-mode`, manual color inputs such as `data-ui-theme-primary-hex`, and\n  `data-ui-theme-target` for scoped live previews. Add `data-ui-theme-export-format`,\n  `data-ui-theme-export`, and `data-ui-theme-output` to copy CSS, Figma variable JSON, or design\n  token JSON. Astro `UIPrimitives` and registered Web Components wire those controls directly;\n  React apps can use `useThemeBuilder` for the same tokens, exports, and control props. Use\n  `createThemePalette`, `createThemeBuilderTokens`, `exportThemeBuilderValue`, `exportThemeCss`,\n  `parseThemeCss`, and `scoreThemeContrast`\n  for theme import/export and accessibility checks. Use `suggestReadableInk`, `mergeThemeTokens`,\n  and `tuneThemeContrast` when generated palettes need readable foreground repair.\n- Use `RichTextEditor` with `ButtonGroup`, `ToggleGroup`, and `Textarea` for editor compositions.\n  Controls with `data-ui-editor-command` dispatch browser editing commands and emit\n  `ui:editor-command`; use `data-ui-editor-value` for headings, links, and other value-bearing\n  commands. Editable surfaces support common formatting shortcuts, synchronize toggle\n  `aria-pressed` state, and emit `ui:editor-change` with HTML and plain text. Astro `UIPrimitives`\n  and registered Web Components bind those controls directly; React apps can use\n  `useRichTextEditor` for `rootProps`, `getCommandProps`, `getEditableProps`, and `executeCommand`.\n  For Tiptap, ProseMirror, Lexical, or Markdown engines, keep the external editor\n  package in the app and bridge toolbar buttons through the emitted command event instead of adding\n  the editor engine to Lumen.\n- Use `Autocomplete`, `SearchField`, `NumberField`, `TimeField`, `DateRangePicker`, `ColorPicker`,\n  and `TagGroup` when forms need more than plain text inputs. Add `data-ui-form` to forms that\n  should reflect native Constraint Validation API state into `Field` error slots on blur and submit.\n  For `InputOTP`, Astro `UIPrimitives` and registered Web Components render/sync a real native input\n  with visual OTP segments; React apps can use the `InputOTP` component or `useInputOTP` for the\n  same sanitization, paste handling, and caret navigation.\n  For `DateRangePicker`, Astro `UIPrimitives` and registered Web Components sync the paired native\n  date input `min`/`max` constraints directly; React apps can use `useDateRangePicker` for the same\n  start/end syncing props.\n  Use native attributes such as `required`, `pattern`, `min`, `max`, and `type`; add\n  `data-error-required`, `data-error-pattern`, `data-error-min`, `data-error-max`, or\n  `data-error-custom` when a control needs custom copy. Listen for `ui:validate` to call\n  `control.setCustomValidity(message)` before the runtime reads validity, and listen for\n  `ui:invalid` or `ui:valid` on the form for submission state. Astro `UIPrimitives` and registered\n  Web Components bind `data-ui-form` directly; React apps can use `useFormValidation` with `Field`\n  to get the same control props, CustomEvents, and error slot updates.\n- Use `Toast` for transient feedback. Static `<Toast>` markup works without\n  JavaScript. With Astro `UIPrimitives` or registered Web Components, create toasts with\n  `window.LumenToast.create(detail)`, `LumenToast.create(detail)` from `@santi020k/lumen-elements`,\n  or `document.dispatchEvent(new CustomEvent('ui:toast', { detail }))`; update them with\n  `.update(id, detail)` or `ui:toast-update`; and dismiss them with `.dismiss(id?)` or\n  `ui:toast-dismiss`. `detail` supports `title`, `description`, `variant`, `duration`, `placement`,\n  `max`, and `action: { label, value }`. Destructive toasts use `role=\"alert\"`; other variants use\n  `role=\"status\"`. Runtime toasts pause their timeout on hover or focus, and Escape dismisses the\n  focused toast.\n\n## Runtime CustomEvents\n\nWhen `UIPrimitives` is mounted, or when Web Components are registered for matching behavior, Lumen\nuses these CustomEvents:\n\n| Event | Target | Detail | Fires When |\n| --- | --- | --- | --- |\n| `ui:data-table-selection-change` | `DataTable` root `[data-ui-datatable]` | `{ values: string[] }` | Selectable row checkboxes, the select-all checkbox, or form reset changes selected row values. |\n| `ui:schedule-change` | `Schedule` root `[data-ui-schedule]` | `{ eventId?: string, slot?: string }` | A draggable schedule event is dropped on a `[data-ui-schedule-slot]`. |\n| `ui:virtual-list-range` | `VirtualList` root `[data-ui-virtual-list]` | `{ startIndex: number, endIndex: number }` | The virtual list calculates its visible range on init or scroll. |\n| `ui:tag-remove` | `TagGroup` root `.ui-tag-group` or `[data-ui-tag-group]` | `{ value?: string }` | A `[data-ui-tag-remove]` control removes its closest tag or list item. |\n| `ui:editor-command` | `RichTextEditor` root `[data-ui-rich-text-editor]` | `{ command: string, executed: boolean, value?: string }` | A toolbar control or keyboard shortcut runs an editor command. |\n| `ui:editor-change` | `RichTextEditor` root `[data-ui-rich-text-editor]` | `{ html: string, text: string }` | Editable content changes or an editor command runs. |\n| `ui:theme-change` | `ThemeBuilder` root `[data-ui-theme-builder]` | `{ hue: number, accentHue: number, mode: 'generated' \\| 'manual', scheme: 'dark' \\| 'light', tokens: Record<string, string> }` | Hue, manual color, mode, or scheme controls update generated tokens. |\n| `ui:theme-export` | `ThemeBuilder` root `[data-ui-theme-builder]` | `{ css?: string, format: 'css' \\| 'figma' \\| 'tokens', tokens: Record<string, string> \\| null, value: string }` | A `[data-ui-theme-export]` control writes the selected export to the output and clipboard when available. |\n| `ui:validate` | Form `[data-ui-form]` | `{ control, form, value }` | Before validation state is read, so custom code can call `control.setCustomValidity(message)`. |\n| `ui:invalid` | Form `[data-ui-form]` | `{ control?, controls?, form }` | Blur or submit validation finds invalid controls. Failed submits focus the first invalid control. |\n| `ui:valid` | Form `[data-ui-form]` | `{ control?, controls?, form }` | Blur or submit validation finds the checked control or form valid. |\n| `ui:toast` | `document` | `{ id?, title?, description?, variant?, duration?, placement?, action? }` | Creates a runtime toast in the matching notification viewport. |\n| `ui:toast-update` | `document` | `{ id, title?, description?, variant?, duration? }` | Updates a runtime toast. |\n| `ui:toast-dismiss` | `document` | `{ id? }` | Dismisses one runtime toast, or all runtime toasts when `id` is omitted. |\n| `ui:toast-action` | Toast `[data-ui-toast]` | `{ id, value? }` | A runtime toast action button is pressed, unless the action specifies a custom event name. |\n\n## Registry Helper\n\n`@santi020k/lumen` exports typed component, recipe, and documentation metadata from\n`@santi020k/lumen/registry`. The package also ships a small `lumen` binary. Individual components\nare addressable by name, including kebab-case aliases such as `data-table`:\n\n```bash\nlumen list\nlumen show Button\nlumen show data-table\nlumen add Button\nlumen add Button --target react\nlumen add Button --target elements\nlumen add data-table\nlumen show scheduler\nlumen add scheduler\nlumen add scheduler --target react\nlumen add scheduler --target elements\nlumen add scheduler --dry-run\nlumen add scheduler --fail-on-conflict\nlumen add scheduler --force\nlumen add scheduler --merge\nlumen list --registry ./registry/lumen.registry.json\nlumen add custom-recipe --registry ./registry/custom.registry.json\nlumen add private-recipe --registry https://example.com/lumen.registry.json --registry-token \"$TOKEN\"\nlumen install\n```\n\n`lumen add <component>` defaults to an Astro wrapper. Use `--target react` for a local React wrapper\nor `--target elements` for a custom-elements starter. Bundled recipes also accept `--target astro`,\n`--target react`, and `--target elements`; external registry inline files keep their authored paths\nand sources.\n\nBefore inventing a wrapper or custom class pattern, check the component source in\n`packages/astro/components`. Astro is the reference implementation for props, class names, data\nattributes, and accessible markup.\n\n## Styling Rules for Generated Code\n\n- Do not require consumers to configure Tailwind for Lumen components.\n- Prefer component props and composition before adding custom CSS.\n- Use the shared token names for custom surfaces: `canvas`, `surface`, `surface-muted`,\n  `surface-strong`, `line`, `ink`, `ink-soft`, `ink-muted`, `brand`, `brand-solid`, `brand-soft`,\n  `accent`, `success`, `warning`, and `danger`.\n- Use `glass` as a boolean prop or attribute for glass surfaces when supported.\n- Do not generate `surface=\"glass\"` for overlays; it is a deprecated alias that maps to `glass`.\n- Preserve semantic labels, keyboard paths, focus states, and native form attributes.\n\n## Figma Handoff\n\nUse `exportThemeFigmaVariables` from `@santi020k/lumen-core/figma` when a design workflow needs\nFigma variable-friendly color values, and `exportThemeDesignTokens` when exporting standard design\ntoken JSON for token importers. See [docs/figma.md](figma.md) for the recommended Figma workflow.\n\n## When Editing This Repo\n\n- Shared contracts belong in `packages/core`.\n- Astro implementation and standalone CSS belong in `packages/astro`.\n- React-specific primitives belong in `packages/react`.\n- Web Component-specific primitives belong in `packages/elements`.\n- Update the relevant package README when public usage changes.\n- Add tests beside package code as `*.test.ts` when behavior, exported metadata, or component\n  contracts change.\n",
-    "readme": "<p align=\"center\">\n  <a href=\"https://lumen.santi020k.com\">\n    <img src=\"./apps/docs/public/logo.svg\" alt=\"Lumen UI\" width=\"239\" height=\"60\">\n  </a>\n</p>\n\n<h1 align=\"center\">Lumen UI</h1>\n\n<p align=\"center\">\n  A multi-framework UI system with 123 accessible primitives for Astro, React, and Web Components.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://lumen.santi020k.com\">Documentation</a>\n  ·\n  <a href=\"https://lumen.santi020k.com/docs/components\">Components</a>\n  ·\n  <a href=\"https://www.figma.com/community/file/1662337342676541513\">Figma library</a>\n  ·\n  <a href=\"https://github.com/santi020k/lumen/issues\">Issues</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/santi020k/lumen/actions\"><img alt=\"GitHub Actions\" src=\"https://img.shields.io/github/actions/workflow/status/santi020k/lumen/ci.yml?branch=main&style=flat-square\"></a>\n  <a href=\"https://www.npmjs.com/package/@santi020k/lumen-astro\"><img alt=\"npm version\" src=\"https://img.shields.io/npm/v/@santi020k/lumen-astro?style=flat-square&label=npm\"></a>\n  <a href=\"./LICENSE\"><img alt=\"MIT license\" src=\"https://img.shields.io/badge/license-MIT-111827?style=flat-square\"></a>\n</p>\n\nLumen gives applications a consistent visual language without tying them to one rendering model.\nIts packages share tokens, component contracts, styles, and interaction patterns while keeping each\nframework's native authoring experience.\n\n- **Framework native:** Astro components, React primitives, and standards-based custom elements.\n- **Accessible by default:** semantic markup, keyboard paths, focus management, and reduced-motion\n  support are built into the primitives.\n- **Standalone CSS:** no Tailwind configuration is required. Tailwind users get an explicit layer\n  integration.\n- **Progressively enhanced:** Astro interactions use a small client runtime instead of requiring an\n  application framework.\n- **Ready for design and AI workflows:** published Figma resources, a portable agent skill, an MCP\n  server, `llms.txt`, and a machine-readable registry ship alongside the component system.\n\n## Quick start\n\nInstall the package for your framework:\n\n```bash\n# Astro\npnpm add @santi020k/lumen-astro\n\n# React\npnpm add @santi020k/lumen-react\n\n# Web Components\npnpm add @santi020k/lumen-elements\n```\n\n### Astro\n\nImport the stylesheet and mount `UIPrimitives` once in your root layout. The runtime enhances all\ninteractive Lumen markup on the page.\n\n```astro\n---\nimport '@santi020k/lumen-astro/styles.css'\nimport { UIPrimitives } from '@santi020k/lumen-astro'\n---\n\n<html lang=\"en\">\n  <body>\n    <slot />\n    <UIPrimitives />\n  </body>\n</html>\n```\n\n```astro\n---\nimport { Button, Card, Input } from '@santi020k/lumen-astro'\n---\n\n<Card>\n  <label for=\"email\">Email</label>\n  <Input id=\"email\" name=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n  <Button>Subscribe</Button>\n</Card>\n```\n\n### React\n\nLoad the stylesheet once from your app entry or global CSS:\n\n```tsx\nimport '@santi020k/lumen-react/styles.css'\nimport { Button, Card, Input } from '@santi020k/lumen-react'\n\nexport function SubscribeForm() {\n  return (\n    <Card>\n      <label htmlFor=\"email\">Email</label>\n      <Input id=\"email\" name=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n      <Button>Subscribe</Button>\n    </Card>\n  )\n}\n```\n\n### Web Components\n\nImport the styles and register the elements once:\n\n```html\n<style>\n  @import \"@santi020k/lumen-elements/styles.css\";\n</style>\n\n<script type=\"module\">\n  import { defineLumenElements } from '@santi020k/lumen-elements/define'\n\n  defineLumenElements()\n</script>\n\n<lumen-card>\n  <label for=\"email\">Email</label>\n  <lumen-input id=\"email\" name=\"email\" type=\"email\" placeholder=\"you@example.com\"></lumen-input>\n  <lumen-button>Subscribe</lumen-button>\n</lumen-card>\n```\n\nSee the [documentation](https://lumen.santi020k.com/docs) for installation, theming, component\nexamples, and API details.\n\n## Tailwind CSS\n\nKeep the layer prelude, Tailwind import, and Lumen stylesheet in the same shared CSS entry. Replace\n`lumen-astro` with the package for your framework.\n\n```css\n@import \"@santi020k/lumen-astro/layers.css\";\n@import \"tailwindcss\";\n@import \"@santi020k/lumen-astro/styles.css\";\n```\n\nThis order places Tailwind base styles before Lumen components and Tailwind utilities above Lumen\ncomponent defaults.\n\n## Packages\n\n| Package | Purpose |\n| --- | --- |\n| [`@santi020k/lumen-astro`](./packages/astro) | Reference implementation, Astro components, and progressive-enhancement runtime |\n| [`@santi020k/lumen-react`](./packages/react) | React components and behavior hooks |\n| [`@santi020k/lumen-elements`](./packages/elements) | Standards-based Web Components |\n| [`@santi020k/lumen-core`](./packages/core) | Shared tokens, metadata, class helpers, and behavior contracts |\n| [`@santi020k/lumen`](./packages/lumen) | Umbrella package, CLI, registry metadata, and public package map |\n| [`@santi020k/lumen-mcp`](./packages/mcp) | MCP server for component discovery and source retrieval |\n\n## AI and design workflows\n\nInstall the portable Lumen skill in Codex, Claude Code, Cursor, Windsurf, and other compatible\ncoding agents:\n\n```bash\nnpx skills add santi020k/lumen --skill lumen-ui\n```\n\nThe skill teaches agents how to select, compose, theme, and verify Lumen primitives. Pair it with\n[`@santi020k/lumen-mcp`](./packages/mcp) when an agent needs to search the live catalog or retrieve\ncurrent source, props, tokens, and usage rules.\n\nAdditional machine-readable surfaces include:\n\n- [`llms.txt`](./llms.txt) for a concise project map.\n- [`docs/ai-usage.md`](./docs/ai-usage.md) for downstream generation examples.\n- [`registry/lumen.registry.json`](./registry/lumen.registry.json) for recipes and installable file\n  groups.\n- [`docs/figma.md`](./docs/figma.md) for Figma variables and Code Connect workflows.\n\n## Contributing\n\nLumen is a pnpm workspace. Astro is the reference implementation; shared contracts belong in\n`packages/core`, while framework-specific behavior stays in its adapter package.\n\n```bash\npnpm install\npnpm run dev\npnpm run validate\n```\n\nRead [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a pull request. User-visible package\nchanges require a changeset.\n\n## License\n\nLumen is available under the [MIT License](./LICENSE).\n"
+    "aiUsage": "# AI Usage Guide\n\nUse this guide when an AI agent is building an app with Lumen or updating examples that teach\nanother agent how to use the library.\n\n## Install the Lumen Agent Skill\n\nLumen ships a portable Agent Skill for AI coding tools that support the open `SKILL.md` format:\n\n```bash\nnpx skills add santi020k/lumen --skill lumen-ui\n```\n\nThe source lives in [`skills/lumen-ui`](../skills/lumen-ui). The skill provides the durable\nframework-selection, component-composition, theming, accessibility, and verification workflow.\nUse it by naming `$lumen-ui` in a prompt, or let a compatible agent trigger it from Lumen-specific\nrequests.\n\nThe skill and MCP server complement each other: the skill explains how to work, while\n`@santi020k/lumen-mcp` supplies structured catalog search, framework-specific contracts, recipes,\nsource, tokens, resources, and rules.\n\n## Pick the Right Package\n\nUse the framework requested by the user. Every adapter shares the same Lumen foundation.\n\n| App Target | Install | Import Components From | Load Styles From |\n| --- | --- | --- | --- |\n| Astro | `@santi020k/lumen-astro` | `@santi020k/lumen-astro` | `@santi020k/lumen-astro/styles.css` |\n| React | `@santi020k/lumen-react` | `@santi020k/lumen-react` | `@santi020k/lumen-react/styles.css` |\n| Web Components | `@santi020k/lumen-elements` | `@santi020k/lumen-elements/define` | `@santi020k/lumen-elements/styles.css` |\n| Package metadata | `@santi020k/lumen-core` | `@santi020k/lumen-core` | Not applicable |\n| Optional brand icons | `@santi020k/lumen-icons-brand` | Register once, then use the framework `Icon` | Uses framework styles |\n\nEach framework package includes the shared foundation. Install `@santi020k/lumen` separately only\nwhen you need its framework-neutral CLI or registry metadata.\n\nBrand marks are intentionally excluded from the default Lucide catalog. When a product needs them,\ninstall and register the optional pack once before rendering a namespaced icon:\n\n```ts\nimport { registerLumenBrandIcons } from '@santi020k/lumen-icons-brand'\n\nregisterLumenBrandIcons()\n```\n\nThen use any canonical Font Awesome Free brand name, such as `brand:github`, `brand:discord`,\n`brand:figma`, `brand:linkedin`, `brand:whatsapp`, or `brand:youtube`, through the existing Astro,\nReact, or Web Component `Icon` API. The package also provides `brand:x` as an alias for\n`brand:x-twitter`.\n\nBrand marks keep their recognizable filled geometry instead of being redrawn as Lucide outlines.\nThey still inherit the same Lumen size, alignment, `currentColor`, and accessible-label behavior as\nthe default icon catalog.\n\n## MCP-Assisted Workflow\n\nConnect `@santi020k/lumen-mcp` when the agent supports Model Context Protocol. The server returns\nvalidated structured content as well as readable text, so agents can select components without\nscraping documentation.\n\n```bash\ncodex mcp add lumen -- npx -y @santi020k/lumen-mcp\n```\n\nFor Codex project configuration:\n\n```toml\n[mcp_servers.lumen]\nenabled = true\ncommand = \"npx\"\nargs = [\"-y\", \"@santi020k/lumen-mcp\"]\n```\n\nUse this sequence:\n\n1. Read `lumen://meta` and `lumen://diagnostics` to identify and verify the snapshot.\n2. Read `lumen://rules`.\n3. Search for the use case with `lumen_search`, passing the target `framework` when known.\n4. Inspect the selected framework with `lumen_get_component` and `detail: \"usage\"`.\n5. Follow its framework behavior setup and hook/controller contract.\n6. Read related multi-component guidance with `lumen_get_recipe`.\n7. Request `detail: \"source\"` only when the usage contract is insufficient.\n8. Read `lumen://tokens` before introducing custom styling.\n9. Retain `lumen://catalog-manifest` and use `lumen_diff_catalog` after upgrades to identify contracts that need refreshing.\n\nExample framework-aware component request:\n\n```json\n{\n  \"name\": \"lumen_get_component\",\n  \"arguments\": {\n    \"name\": \"DateRangePicker\",\n    \"framework\": \"react\",\n    \"detail\": \"usage\"\n  }\n}\n```\n\nStable resources are available at `lumen://rules`, `lumen://tokens`, `lumen://components`,\n`lumen://meta`, `lumen://catalog-manifest`, `lumen://diagnostics`,\n`lumen://components/{name}`, and `lumen://recipes/{name}`. See\n[`packages/mcp/README.md`](../packages/mcp/README.md) for Claude Desktop, Cursor, generic stdio,\nlocal repository, and programmatic examples.\n\n## Minimal Setup\n\nImport the stylesheet once in the app's global CSS, root layout, or app entry.\n\n```css\n@import \"@santi020k/lumen-react/styles.css\";\n```\n\nIf Tailwind is present, keep both imports in the same shared CSS entry.\n\n```css\n@import \"@santi020k/lumen-react/layers.css\";\n@import \"tailwindcss\";\n@import \"@santi020k/lumen-react/styles.css\";\n```\n\nKeep the layer prelude first. It places Tailwind base styles below Lumen components and Tailwind\nutilities above them, so consumer spacing, display, radius, width, and responsive visibility\nclasses override Lumen defaults predictably.\n\nAstro apps should mount `UIPrimitives` once in the root layout when using interactive primitives\nsuch as dialogs, menus, popovers, tabs, carousels, command lists, toggles, validated forms, or\ntoasts. Do not place `UIPrimitives` in each component example or next to each primitive instance;\none root include enhances all matching `data-ui-*` markup on the page.\n\n```astro\n---\nimport { UIPrimitives } from '@santi020k/lumen-astro'\n---\n\n<UIPrimitives />\n```\n\n## Astro\n\nUse direct named imports from `@santi020k/lumen-astro`.\n\n```astro\n---\nimport { Button, Card, Input, Label } from '@santi020k/lumen-astro'\n---\n\n<Card>\n  <Label for=\"email\">Email</Label>\n  <Input id=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n  <Button type=\"submit\">Subscribe</Button>\n</Card>\n```\n\n`Stat` defaults to a `div`. Choose `as=\"article\"` for a self-contained metric with supporting\ncontent, or `as=\"section\"` for a labeled region. Do not use a semantic root solely for styling.\nIts visual variants are `default`, `accent`, and `glass`; reserve `accent` for featured metrics and\nkeep glass selective.\n\nFor long reading surfaces, use `Anchor` for local section navigation and pass each item’s optional\nheading `depth` when hierarchy matters. Use `ScrollProgress` for document position; keep `Progress`\nfor application-controlled task completion. `Pill` accepts `neutral`, `brand`, and `outline`\nvariants, plus native link and count composition.\n\n## React\n\nReact components share the same visual classes and data attributes as Astro components. For\nbehavior-heavy primitives, use the React behavior hooks from `@santi020k/lumen-react` (`useDialog`,\n`usePopover`, `useDropdownMenu`, `useTabs`, `useSelect`, `useToast`, and `useTooltip`), which track\nthe Astro runtime's ARIA, keyboard, Escape, dismissal, and toast controller semantics.\n\nThe React package entry is a client boundary. In Next.js, it can be imported by a Server Component\nwithout evaluating Lumen's contexts and hooks in the React server runtime; the rendered Lumen\nsubtree becomes a Client Component boundary. Vite and other client-rendered React applications use\nthe same entry without additional setup.\n`Button`, `Link`, `ButtonLink`, and `Input` accept React 19 DOM refs directly as props.\n`Button asChild` composes the button contract onto one child element, while `Input visualSize` controls\npresentation without shadowing the native numeric `size` attribute.\n`Stat as` and `variant` follow the same semantic-root and visual guidance as the Astro component.\n\n```tsx\nimport '@santi020k/lumen-react/styles.css'\nimport { Button, Card, Input, Label } from '@santi020k/lumen-react'\n\nexport function SubscribeForm() {\n  return (\n    <Card>\n      <Label htmlFor=\"email\">Email</Label>\n      <Input id=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n      <Button type=\"submit\">Subscribe</Button>\n    </Card>\n  )\n}\n```\n\n## Web Components\n\nRegister custom elements once, then use `lumen-*` tags in HTML. The elements adapter includes\ninteractive behavior parity for DataTable, Dialog, Popover, DropdownMenu, ContextMenu, Tabs,\nSelect, ThemeBuilder, Toast, Tooltip, forms, RichTextEditor, Schedule, and VirtualList: selection,\nvalidation, rich text command, context menu, schedule drag/drop, theme, and range events, ARIA\nstate, roving/listbox keyboard paths, Escape/outside dismissal, focus return/trapping, native\nselect form participation, and the same toast controller events as the Astro runtime.\n\n```html\n<script type=\"module\">\n  import { defineLumenElements } from '@santi020k/lumen-elements/define'\n\n  defineLumenElements()\n</script>\n\n<lumen-card>\n  <label for=\"email\">Email</label>\n  <lumen-input id=\"email\" type=\"email\" placeholder=\"you@example.com\"></lumen-input>\n  <lumen-button type=\"submit\">Subscribe</lumen-button>\n</lumen-card>\n```\n\n## Component Selection\n\nThe shared catalog includes:\n\n`Accordion`, `Alert`, `AlertDialog`, `Agenda`, `AspectRatio`, `Attachment`, `Autocomplete`,\n`Avatar`, `Badge`, `BarChart`, `Breadcrumb`, `Bubble`, `Button`, `ButtonGroup`, `Calendar`, `Card`,\n`Carousel`, `Chart`, `Checkbox`, `Collapsible`, `Code`, `Combobox`, `Command`, `ColorPicker`,\n`ContextMenu`, `DataTable`, `DatePicker`, `DateRangePicker`, `Dialog`, `Direction`, `Drawer`,\n`DropdownMenu`, `Empty`, `Field`, `HoverCard`, `Icon`, `Input`, `InputGroup`, `InputOTP`, `Item`, `Kbd`,\n`Label`, `LineChart`, `Marker`, `Menubar`, `Message`, `MessageScroller`, `NativeSelect`, `NavigationMenu`,\n`NumberField`, `Pagination`, `PieChart`, `Popover`, `Progress`, `RadioGroup`, `Resizable`, `RichTextEditor`,\n`ScrollArea`, `Schedule`, `SearchField`, `Select`, `Separator`, `Sheet`, `Sidebar`, `Skeleton`,\n`Slider`, `Sparkline`, `Spinner`, `Switch`, `Table`, `Tabs`, `TagGroup`, `Textarea`, `ThemeBuilder`,\n`TimeField`, `Toast`, `Toggle`, `ToggleGroup`, `Tooltip`, `Tree`, `TreeGrid`, `Typography`, and\n`VirtualList`.\n\n## Product Recipes\n\n- Use `Sparkline` for a compact trend beside a labelled metric, `BarChart` for categorical\n  comparison, `LineChart` for ordered or time-series data, and `PieChart` for a small\n  part-to-whole breakdown. Pass already-aggregated `LumenChartSeries` data; keep statistics,\n  resampling, model evaluation, and domain calculations in application code. Keep `showTable`\n  enabled unless the same values are already available in a nearby semantic table. Prefer a bar\n  chart when precise slice comparison matters or the pie would exceed roughly seven categories.\n  Use `Chart` as the custom SVG/canvas escape hatch.\n- Use `Icon name=\"search\"` or any Lucide icon name for standard interface pictograms. Kebab-case\n  names and Lucide aliases work. Pair decorative icons with `decorative`, and pass `label` only\n  when the icon carries meaning on its own. Install and register\n  `@santi020k/lumen-icons-brand` for supported brand marks, then use names such as\n  `brand:github`. Render project-specific or unsupported brand SVGs through the default `Icon`\n  slot. Astro reports unknown named icons during development instead of failing silently.\n- Use `Schedule` with `Agenda`, `Calendar`, and `DatePicker` for booking, CRM, content calendar, and\n  event planning screens. Mark slots with `data-ui-schedule-slot` and events with\n  `data-ui-schedule-event`; the runtime emits `ui:schedule-change` when a draggable event is moved.\n  `Calendar` renders a hidden input plus selectable date grid; Astro `UIPrimitives` and registered\n  Web Components wire month navigation and roving keyboard focus directly, while React apps can use\n  the `Calendar` component or `useCalendar` for the same date selection contract.\n  Astro `UIPrimitives` and registered Web Components bind schedule drag/drop directly; React apps\n  can use `useSchedule` for `rootProps`, `getEventProps`, `getSlotProps`, and `ui:schedule-change`\n  parity. Use `createScheduleSlots`, `moveScheduleEvent`, and `expandRecurringScheduleEvent` from\n  `@santi020k/lumen-core` for reusable schedule state; use `getScheduleConflicts` and\n  `canPlaceScheduleEvent` before committing drag/drop changes. Persist local schedule edits with\n  `createScheduleStorageKey`, `saveScheduleEvents`, and `loadScheduleEvents` against any\n  `localStorage`-compatible adapter. Use `resizeScheduleEvent` and `resizeScheduleEvents` for\n  snap-to-grid resize handles.\n- Use `DataTable`, `Tree`, `TreeGrid`, `VirtualList`, `Pagination`, and `Command` for dense data\n  collection workflows. Astro and Elements wire selectable/sortable `DataTable` behavior and\n  `VirtualList` range events; React emits the same data attributes for app-level adapters. `Tree`\n  and `TreeGrid` use roving keyboard focus, and `VirtualList` emits `ui:virtual-list-range` as the\n  rendered range changes. Use `createDataViewState`,\n  `serializeDataViewState`, `parseDataViewState`, `applyDataViewState`, and `getVirtualRange` for\n  saved views, filtering, sorting, pagination, and virtualization math. Use\n  `createDataViewStorageKey`, `saveDataViewState`, and `loadDataViewState` when saved views should\n  survive navigation or reloads. Use `pinDataViewColumn`, `unpinDataViewColumn`,\n  `toggleDataViewSelection`, `createDataViewSearchParams`, and `createDataViewServerRequest` when\n  connecting dense views to router state or server-backed data.\n- Use `Resizable` for split-pane editors, dashboards, inspectors, and side-by-side review layouts.\n  Astro `UIPrimitives` and registered Web Components generate separator handles and pane sizing\n  directly; React apps can use the `Resizable` component or `useResizable` for pointer, keyboard,\n  min/max, and double-click reset parity.\n- Use `ThemeBuilder`, `ColorPicker`, `Card`, `Button`, and `Input` to build token preview and export\n  tools. Add `data-ui-theme-brand-hue`, `data-ui-theme-accent-hue`, `data-ui-theme-scheme`,\n  `data-ui-theme-mode`, manual color inputs such as `data-ui-theme-primary-hex`, and\n  `data-ui-theme-target` for scoped live previews. Add `data-ui-theme-export-format`,\n  `data-ui-theme-export`, and `data-ui-theme-output` to copy CSS, Figma variable JSON, or design\n  token JSON. Astro `UIPrimitives` and registered Web Components wire those controls directly;\n  React apps can use `useThemeBuilder` for the same tokens, exports, and control props. Use\n  `createThemePalette`, `createThemeBuilderTokens`, `exportThemeBuilderValue`, `exportThemeCss`,\n  `parseThemeCss`, and `scoreThemeContrast`\n  for theme import/export and accessibility checks. Use `suggestReadableInk`, `mergeThemeTokens`,\n  and `tuneThemeContrast` when generated palettes need readable foreground repair.\n- Use `RichTextEditor` with `ButtonGroup`, `ToggleGroup`, and `Textarea` for editor compositions.\n  Controls with `data-ui-editor-command` dispatch browser editing commands and emit\n  `ui:editor-command`; use `data-ui-editor-value` for headings, links, and other value-bearing\n  commands. Editable surfaces support common formatting shortcuts, synchronize toggle\n  `aria-pressed` state, and emit `ui:editor-change` with HTML and plain text. Astro `UIPrimitives`\n  and registered Web Components bind those controls directly; React apps can use\n  `useRichTextEditor` for `rootProps`, `getCommandProps`, `getEditableProps`, and `executeCommand`.\n  For Tiptap, ProseMirror, Lexical, or Markdown engines, keep the external editor\n  package in the app and bridge toolbar buttons through the emitted command event instead of adding\n  the editor engine to Lumen.\n- Use `Autocomplete`, `SearchField`, `NumberField`, `TimeField`, `DateRangePicker`, `ColorPicker`,\n  and `TagGroup` when forms need more than plain text inputs. Add `data-ui-form` to forms that\n  should reflect native Constraint Validation API state into `Field` error slots on blur and submit.\n  For `InputOTP`, Astro `UIPrimitives` and registered Web Components render/sync a real native input\n  with visual OTP segments; React apps can use the `InputOTP` component or `useInputOTP` for the\n  same sanitization, paste handling, and caret navigation.\n  For `DateRangePicker`, Astro `UIPrimitives` and registered Web Components sync the paired native\n  date input `min`/`max` constraints directly; React apps can use `useDateRangePicker` for the same\n  start/end syncing props.\n  Use native attributes such as `required`, `pattern`, `min`, `max`, and `type`; add\n  `data-error-required`, `data-error-pattern`, `data-error-min`, `data-error-max`, or\n  `data-error-custom` when a control needs custom copy. Listen for `ui:validate` to call\n  `control.setCustomValidity(message)` before the runtime reads validity, and listen for\n  `ui:invalid` or `ui:valid` on the form for submission state. Astro `UIPrimitives` and registered\n  Web Components bind `data-ui-form` directly; React apps can use `useFormValidation` with `Field`\n  to get the same control props, CustomEvents, and error slot updates.\n- Use `Toast` for transient feedback. Static `<Toast>` markup works without\n  JavaScript. With Astro `UIPrimitives` or registered Web Components, create toasts with\n  `window.LumenToast.create(detail)`, `LumenToast.create(detail)` from `@santi020k/lumen-elements`,\n  or `document.dispatchEvent(new CustomEvent('ui:toast', { detail }))`; update them with\n  `.update(id, detail)` or `ui:toast-update`; and dismiss them with `.dismiss(id?)` or\n  `ui:toast-dismiss`. `detail` supports `title`, `description`, `variant`, `duration`, `placement`,\n  `max`, and `action: { label, value }`. Destructive toasts use `role=\"alert\"`; other variants use\n  `role=\"status\"`. Runtime toasts pause their timeout on hover or focus, and Escape dismisses the\n  focused toast.\n\n## Runtime CustomEvents\n\nWhen `UIPrimitives` is mounted, or when Web Components are registered for matching behavior, Lumen\nuses these CustomEvents:\n\n| Event | Target | Detail | Fires When |\n| --- | --- | --- | --- |\n| `ui:data-table-selection-change` | `DataTable` root `[data-ui-datatable]` | `{ values: string[] }` | Selectable row checkboxes, the select-all checkbox, or form reset changes selected row values. |\n| `ui:schedule-change` | `Schedule` root `[data-ui-schedule]` | `{ eventId?: string, slot?: string }` | A draggable schedule event is dropped on a `[data-ui-schedule-slot]`. |\n| `ui:virtual-list-range` | `VirtualList` root `[data-ui-virtual-list]` | `{ startIndex: number, endIndex: number }` | The virtual list calculates its visible range on init or scroll. |\n| `ui:tag-remove` | `TagGroup` root `.ui-tag-group` or `[data-ui-tag-group]` | `{ value?: string }` | A `[data-ui-tag-remove]` control removes its closest tag or list item. |\n| `ui:editor-command` | `RichTextEditor` root `[data-ui-rich-text-editor]` | `{ command: string, executed: boolean, value?: string }` | A toolbar control or keyboard shortcut runs an editor command. |\n| `ui:editor-change` | `RichTextEditor` root `[data-ui-rich-text-editor]` | `{ html: string, text: string }` | Editable content changes or an editor command runs. |\n| `ui:theme-change` | `ThemeBuilder` root `[data-ui-theme-builder]` | `{ hue: number, accentHue: number, mode: 'generated' \\| 'manual', scheme: 'dark' \\| 'light', tokens: Record<string, string> }` | Hue, manual color, mode, or scheme controls update generated tokens. |\n| `ui:theme-export` | `ThemeBuilder` root `[data-ui-theme-builder]` | `{ css?: string, format: 'css' \\| 'figma' \\| 'tokens', tokens: Record<string, string> \\| null, value: string }` | A `[data-ui-theme-export]` control writes the selected export to the output and clipboard when available. |\n| `ui:validate` | Form `[data-ui-form]` | `{ control, form, value }` | Before validation state is read, so custom code can call `control.setCustomValidity(message)`. |\n| `ui:invalid` | Form `[data-ui-form]` | `{ control?, controls?, form }` | Blur or submit validation finds invalid controls. Failed submits focus the first invalid control. |\n| `ui:valid` | Form `[data-ui-form]` | `{ control?, controls?, form }` | Blur or submit validation finds the checked control or form valid. |\n| `ui:toast` | `document` | `{ id?, title?, description?, variant?, duration?, placement?, action? }` | Creates a runtime toast in the matching notification viewport. |\n| `ui:toast-update` | `document` | `{ id, title?, description?, variant?, duration? }` | Updates a runtime toast. |\n| `ui:toast-dismiss` | `document` | `{ id? }` | Dismisses one runtime toast, or all runtime toasts when `id` is omitted. |\n| `ui:toast-action` | Toast `[data-ui-toast]` | `{ id, value? }` | A runtime toast action button is pressed, unless the action specifies a custom event name. |\n\n## Registry Helper\n\n`@santi020k/lumen` exports typed component, recipe, and documentation metadata from\n`@santi020k/lumen/registry`. The package also ships a small `lumen` binary. Individual components\nare addressable by name, including kebab-case aliases such as `data-table`:\n\n```bash\nlumen list\nlumen show Button\nlumen show data-table\nlumen add Button\nlumen add Button --target react\nlumen add Button --target elements\nlumen add data-table\nlumen show scheduler\nlumen add scheduler\nlumen add scheduler --target react\nlumen add scheduler --target elements\nlumen add scheduler --dry-run\nlumen add scheduler --fail-on-conflict\nlumen add scheduler --force\nlumen add scheduler --merge\nlumen list --registry ./registry/lumen.registry.json\nlumen add custom-recipe --registry ./registry/custom.registry.json\nlumen add private-recipe --registry https://example.com/lumen.registry.json --registry-token \"$TOKEN\"\nlumen install\n```\n\n`lumen add <component>` defaults to an Astro wrapper. Use `--target react` for a local React wrapper\nor `--target elements` for a custom-elements starter. Bundled recipes also accept `--target astro`,\n`--target react`, and `--target elements`; external registry inline files keep their authored paths\nand sources.\n\nBefore inventing a wrapper or custom class pattern, check the component source in\n`packages/astro/components`. Astro is the reference implementation for props, class names, data\nattributes, and accessible markup.\n\n## Styling Rules for Generated Code\n\n- Do not require consumers to configure Tailwind for Lumen components.\n- Prefer component props and composition before adding custom CSS.\n- Use the shared token names for custom surfaces: `canvas`, `surface`, `surface-muted`,\n  `surface-strong`, `line`, `ink`, `ink-soft`, `ink-muted`, `brand`, `brand-solid`, `brand-soft`,\n  `accent`, `success`, `warning`, and `danger`.\n- Use `glass` as a boolean prop or attribute for glass surfaces when supported.\n- Do not generate `surface=\"glass\"` for overlays; it is a deprecated alias that maps to `glass`.\n- Preserve semantic labels, keyboard paths, focus states, and native form attributes.\n\n## Figma Handoff\n\nUse `exportThemeFigmaVariables` from `@santi020k/lumen-core/figma` when a design workflow needs\nFigma variable-friendly color values, and `exportThemeDesignTokens` when exporting standard design\ntoken JSON for token importers. See [docs/figma.md](figma.md) for the recommended Figma workflow.\n\n## When Editing This Repo\n\n- Shared contracts belong in `packages/core`.\n- Astro implementation and standalone CSS belong in `packages/astro`.\n- React-specific primitives belong in `packages/react`.\n- Web Component-specific primitives belong in `packages/elements`.\n- Update the relevant package README when public usage changes.\n- Add tests beside package code as `*.test.ts` when behavior, exported metadata, or component\n  contracts change.\n",
+    "readme": "<p align=\"center\">\n  <a href=\"https://lumen.santi020k.com\">\n    <img src=\"./apps/docs/public/logo.svg\" alt=\"Lumen UI\" width=\"239\" height=\"60\">\n  </a>\n</p>\n\n<h1 align=\"center\">Lumen UI</h1>\n\n<p align=\"center\">\n  A multi-framework UI system with 123 accessible primitives for Astro, React, and Web Components.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://lumen.santi020k.com\">Documentation</a>\n  ·\n  <a href=\"https://lumen.santi020k.com/docs/components\">Components</a>\n  ·\n  <a href=\"https://www.figma.com/community/file/1662337342676541513\">Figma library</a>\n  ·\n  <a href=\"https://github.com/santi020k/lumen/issues\">Issues</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/santi020k/lumen/actions\"><img alt=\"GitHub Actions\" src=\"https://img.shields.io/github/actions/workflow/status/santi020k/lumen/ci.yml?branch=main&style=flat-square\"></a>\n  <a href=\"https://www.npmjs.com/package/@santi020k/lumen-astro\"><img alt=\"npm version\" src=\"https://img.shields.io/npm/v/@santi020k/lumen-astro?style=flat-square&label=npm\"></a>\n  <a href=\"./LICENSE\"><img alt=\"MIT license\" src=\"https://img.shields.io/badge/license-MIT-111827?style=flat-square\"></a>\n</p>\n\nLumen gives applications a consistent visual language without tying them to one rendering model.\nIts packages share tokens, component contracts, styles, and interaction patterns while keeping each\nframework's native authoring experience.\n\n- **Framework native:** Astro components, React primitives, and standards-based custom elements.\n- **Accessible by default:** semantic markup, keyboard paths, focus management, and reduced-motion\n  support are built into the primitives.\n- **Standalone CSS:** no Tailwind configuration is required. Tailwind users get an explicit layer\n  integration.\n- **Progressively enhanced:** Astro interactions use a small client runtime instead of requiring an\n  application framework.\n- **Ready for design and AI workflows:** published Figma resources, a portable agent skill, an MCP\n  server, `llms.txt`, and a machine-readable registry ship alongside the component system.\n\n## Quick start\n\nInstall the package for your framework:\n\n```bash\n# Astro\npnpm add @santi020k/lumen-astro\n\n# React\npnpm add @santi020k/lumen-react\n\n# Web Components\npnpm add @santi020k/lumen-elements\n```\n\n### Astro\n\nImport the stylesheet and mount `UIPrimitives` once in your root layout. The runtime enhances all\ninteractive Lumen markup on the page.\n\n```astro\n---\nimport '@santi020k/lumen-astro/styles.css'\nimport { UIPrimitives } from '@santi020k/lumen-astro'\n---\n\n<html lang=\"en\">\n  <body>\n    <slot />\n    <UIPrimitives />\n  </body>\n</html>\n```\n\n```astro\n---\nimport { Button, Card, Input } from '@santi020k/lumen-astro'\n---\n\n<Card>\n  <label for=\"email\">Email</label>\n  <Input id=\"email\" name=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n  <Button>Subscribe</Button>\n</Card>\n```\n\n### React\n\nLoad the stylesheet once from your app entry or global CSS:\n\n```tsx\nimport '@santi020k/lumen-react/styles.css'\nimport { Button, Card, Input } from '@santi020k/lumen-react'\n\nexport function SubscribeForm() {\n  return (\n    <Card>\n      <label htmlFor=\"email\">Email</label>\n      <Input id=\"email\" name=\"email\" type=\"email\" placeholder=\"you@example.com\" />\n      <Button>Subscribe</Button>\n    </Card>\n  )\n}\n```\n\n### Web Components\n\nImport the styles and register the elements once:\n\n```html\n<style>\n  @import \"@santi020k/lumen-elements/styles.css\";\n</style>\n\n<script type=\"module\">\n  import { defineLumenElements } from '@santi020k/lumen-elements/define'\n\n  defineLumenElements()\n</script>\n\n<lumen-card>\n  <label for=\"email\">Email</label>\n  <lumen-input id=\"email\" name=\"email\" type=\"email\" placeholder=\"you@example.com\"></lumen-input>\n  <lumen-button>Subscribe</lumen-button>\n</lumen-card>\n```\n\nSee the [documentation](https://lumen.santi020k.com/docs) for installation, theming, component\nexamples, and API details.\n\n## Tailwind CSS\n\nKeep the layer prelude, Tailwind import, and Lumen stylesheet in the same shared CSS entry. Replace\n`lumen-astro` with the package for your framework.\n\n```css\n@import \"@santi020k/lumen-astro/layers.css\";\n@import \"tailwindcss\";\n@import \"@santi020k/lumen-astro/styles.css\";\n```\n\nThis order places Tailwind base styles before Lumen components and Tailwind utilities above Lumen\ncomponent defaults.\n\n## Packages\n\n| Package | Purpose |\n| --- | --- |\n| [`@santi020k/lumen-astro`](./packages/astro) | Reference implementation, Astro components, and progressive-enhancement runtime |\n| [`@santi020k/lumen-react`](./packages/react) | React components and behavior hooks |\n| [`@santi020k/lumen-elements`](./packages/elements) | Standards-based Web Components |\n| [`@santi020k/lumen-core`](./packages/core) | Shared tokens, metadata, class helpers, and behavior contracts |\n| [`@santi020k/lumen-icons-brand`](./packages/icons-brand) | Optional namespaced brand icons for the shared `Icon` API |\n| [`@santi020k/lumen`](./packages/lumen) | Umbrella package, CLI, registry metadata, and public package map |\n| [`@santi020k/lumen-mcp`](./packages/mcp) | MCP server for component discovery and source retrieval |\n\n## AI and design workflows\n\nInstall the portable Lumen skill in Codex, Claude Code, Cursor, Windsurf, and other compatible\ncoding agents:\n\n```bash\nnpx skills add santi020k/lumen --skill lumen-ui\n```\n\nThe skill teaches agents how to select, compose, theme, and verify Lumen primitives. Pair it with\n[`@santi020k/lumen-mcp`](./packages/mcp) when an agent needs to search the live catalog or retrieve\ncurrent source, props, tokens, and usage rules.\n\nAdditional machine-readable surfaces include:\n\n- [`llms.txt`](./llms.txt) for a concise project map.\n- [`docs/ai-usage.md`](./docs/ai-usage.md) for downstream generation examples.\n- [`registry/lumen.registry.json`](./registry/lumen.registry.json) for recipes and installable file\n  groups.\n- [`docs/figma.md`](./docs/figma.md) for Figma variables and Code Connect workflows.\n\n## Contributing\n\nLumen is a pnpm workspace. Astro is the reference implementation; shared contracts belong in\n`packages/core`, while framework-specific behavior stays in its adapter package.\n\n```bash\npnpm install\npnpm run dev\npnpm run validate\n```\n\nRead [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a pull request. User-visible package\nchanges require a changeset.\n\n## License\n\nLumen is available under the [MIT License](./LICENSE).\n"
   },
   "meta": {
-    "catalogHash": "fe40e1272c32ff21e23f31007bf371c3f667aec69779a3af0f34b397a151cc4f",
-    "componentCount": 124,
+    "catalogHash": "d823f5c7ed0ee5c370cf78381b622ef60046afe977464a75f93e6464db4f037d",
+    "componentCount": 129,
     "packages": [
       "@santi020k/lumen-astro",
       "@santi020k/lumen-react",
@@ -24903,16 +26655,16 @@
       "@santi020k/lumen-core"
     ],
     "packageVersions": {
-      "@santi020k/lumen-astro": "0.3.0",
-      "@santi020k/lumen-core": "0.3.0",
-      "@santi020k/lumen-elements": "0.3.0",
-      "@santi020k/lumen-mcp": "0.3.0",
-      "@santi020k/lumen-react": "0.3.0"
+      "@santi020k/lumen-astro": "0.4.0",
+      "@santi020k/lumen-core": "0.4.0",
+      "@santi020k/lumen-elements": "0.4.0",
+      "@santi020k/lumen-mcp": "0.4.0",
+      "@santi020k/lumen-react": "0.4.0"
     },
     "registryName": "lumen",
     "registryVersion": 1,
     "schemaVersion": 3,
-    "serverVersion": "0.3.0"
+    "serverVersion": "0.4.0"
   },
   "recipes": [
     {
@@ -25038,10 +26790,50 @@
         "elements": "lumen add rich-text-editor --target elements",
         "react": "lumen add rich-text-editor --target react"
       }
+    },
+    {
+      "name": "data-visualization",
+      "type": "recipe",
+      "components": [
+        "Chart",
+        "Sparkline",
+        "BarChart",
+        "LineChart",
+        "PieChart",
+        "Stat",
+        "Meter"
+      ],
+      "categories": [
+        "Data display"
+      ],
+      "description": "A data visualization composition using Chart, Sparkline, BarChart, LineChart, PieChart, Stat, Meter.",
+      "install": {
+        "astro": "lumen add data-visualization --target astro",
+        "elements": "lumen add data-visualization --target elements",
+        "react": "lumen add data-visualization --target react"
+      }
     }
   ],
   "rules": "# Lumen UI\n\nLumen is a multi-framework primitive UI system with Astro as the reference implementation.\n\nUse these files first when generating, reviewing, or migrating apps that use Lumen:\n\n- README.md: public overview and package strategy.\n- docs/ai-usage.md: AI-focused setup, package selection, and component selection.\n- skills/lumen-ui/SKILL.md: portable Agent Skill for building, reviewing, and theming Lumen interfaces.\n- docs/feature-roadmap.md: competitor-informed gaps and implementation priorities.\n- registry/lumen.registry.json: installable component, recipe, and documentation manifest.\n- packages/core/src/components.ts: authoritative shared component catalog.\n- packages/astro/components: reference component markup and prop shapes.\n- packages/astro/styles/lumen.css: standalone CSS contract for all frameworks.\n- @santi020k/lumen-mcp: Model Context Protocol server exposing snapshot provenance, structured component discovery, framework-aware usage/source, recipes, tolerant search, tokens, rules, and lumen:// resources for AI agents.\n\nInstall the portable Lumen Agent Skill:\n\n```bash\nnpx skills add santi020k/lumen --skill lumen-ui\n```\n\nDefault usage:\n\n```astro\n---\nimport { Button, Card, Input } from '@santi020k/lumen-astro'\nimport { UIPrimitives } from '@santi020k/lumen-astro'\nimport '@santi020k/lumen-astro/styles.css'\n---\n\n<UIPrimitives />\n<Card>\n  <label for=\"email\">Email</label>\n  <Input id=\"email\" type=\"email\" />\n  <Button>Subscribe</Button>\n</Card>\n```\n\nRules for agents:\n\n- When Lumen MCP is connected, read `lumen://meta`, `lumen://diagnostics`, and `lumen://rules`, pass the target framework to `lumen_search`, and follow the framework behavior returned by `lumen_get_component`. Retain `lumen://catalog-manifest` and use `lumen_diff_catalog` after upgrades when the client supports cached context.\n- Prefer Astro unless the user explicitly targets React or Web Components.\n- In React, use the visual components with behavior hooks for Dialog, Popover, DropdownMenu, Tabs, Select, Toast, and Tooltip instead of mounting the Astro runtime.\n- In Web Components, registered `lumen-*` elements include behavior parity for Dialog, Popover, DropdownMenu, Tabs, Select, Toast, and Tooltip, including ARIA state, keyboard paths, Escape/outside dismissal, focus handling, native select form participation, and the shared toast controller.\n- Do not require Tailwind configuration for Lumen components.\n- Use public tokens: canvas, surface, surface-muted, surface-strong, line, ink, ink-soft, ink-muted, brand, brand-solid, brand-soft, accent, success, warning, danger.\n- Mount `UIPrimitives` once for interactive Astro primitives.\n- Use `glass` for glass surfaces. Overlay `surface=\"glass\"` is a deprecated compatibility alias that maps to `glass`.\n- Treat schedule, data collection, rich text, theme builder, and advanced fields as supported surfaces with progressively enhanced behavior.\n- Use `lumen list`, `lumen show <component>`, and `lumen add <component>` for individually addressable registry components; component names also resolve from kebab-case aliases such as `data-table`.\n- Runtime CustomEvents used by `UIPrimitives`: `ui:data-table-selection-change` from `[data-ui-datatable]` with `{ values }` (`ui:datatable-selection-change` remains a deprecated alias until 1.0); `ui:schedule-change` from `[data-ui-schedule]` with `{ eventId, slot }`; `ui:virtual-list-range` from `[data-ui-virtual-list]` with `{ startIndex, endIndex }`; `ui:tag-remove` from tag groups with `{ value }`; `ui:editor-command` from rich text editors with `{ command }`; `ui:theme-change` from theme builders with `{ hue, tokens }`; `ui:theme-export` from theme builders with `{ css }`; `ui:validate`, `ui:invalid`, and `ui:valid` from `[data-ui-form]` for native Constraint Validation API enhancement; document-level `ui:toast`, `ui:toast-update`, and `ui:toast-dismiss` for runtime toasts; `ui:toast-action` from `[data-ui-toast]` when an action button is pressed.\n- Add `data-ui-form` to forms that should reflect `required`, `pattern`, `min`, `max`, `type`, and custom `setCustomValidity()` state into Field error slots on blur and submit. Use `data-error-required`, `data-error-pattern`, `data-error-min`, `data-error-max`, or `data-error-custom` to override browser validation messages.\n- Toasts use `Sonner` viewports with `placement` and `maxCount`. With `UIPrimitives` or registered Web Components, use `window.LumenToast.create(detail)`, `.update(id, detail)`, and `.dismiss(id?)`, import `LumenToast` from `@santi020k/lumen-elements`, or dispatch the matching document events. Runtime toast `detail` supports `title`, `description`, `variant`, `duration`, `placement`, `max`, and `action`.\n",
   "tokens": {
+    "chart": {
+      "axis": "var(--ink-muted)",
+      "divergingMid": "220 13% 91%",
+      "divergingNegative": "0 84% 60%",
+      "divergingPositive": "221 83% 53%",
+      "grid": "var(--line)",
+      "sequentialHigh": "221 83% 40%",
+      "sequentialLow": "218 100% 97%",
+      "sequentialMid": "221 83% 67%",
+      "series1": "221 83% 53%",
+      "series2": "168 76% 36%",
+      "series3": "280 72% 56%",
+      "series4": "25 95% 53%",
+      "series5": "340 82% 55%",
+      "series6": "190 82% 42%",
+      "series7": "52 92% 45%",
+      "series8": "215 16% 47%"
+    },
     "colors": {
       "accent": "264 95% 57%",
       "brand": "264 92% 47%",