@lostgradient/cinder 0.1.0 → 0.2.0

package/src/components/spectrum-chart/spectrum-chart.svelte

@@ -0,0 +1,247 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status alpha
+   * @purpose Responsive SVG frequency-bin bar chart for visualizing audio spectrum magnitude data.
+   * @tag chart
+   * @tag spectrum
+   * @tag signal
+   * @tag audio
+   * @useWhen Displaying pre-computed frequency-domain magnitude data from an FFT or spectrum analyzer.
+   * @useWhen Showing a static frequency response or spectrum snapshot with labelled frequency bins.
+   * @avoidWhen Real-time live audio spectrum is needed — feed live AnalyserNode data as props yourself.
+   * @avoidWhen A full time × frequency heatmap is needed — use spectrogram instead.
+   * @avoidWhen General categorical bar comparison — use bar-chart instead.
+   * @related waveform, spectrogram, bar-chart
+   */
+  export type { SpectrumChartProps, SpectrumChartSchemaProps } from './spectrum-chart.types.ts';
+</script>
+
+<script lang="ts">
+  import { dataTableClass, formatNumericValue } from '../../_internal/chart/chart-utilities.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { SpectrumChartProps } from './spectrum-chart.types.ts';
+
+  let {
+    label,
+    description,
+    bins,
+    height = 160,
+    loading = false,
+    dataTableVisibility = 'screen-reader-only',
+    dataTableCaption,
+    class: customClassName,
+    empty,
+    loadingContent,
+    id,
+    ...rest
+  }: SpectrumChartProps = $props();
+
+  const generatedId = $props.id();
+  const rootId = $derived(id ?? generatedId);
+  const descriptionId = $derived(description ? `${rootId}-description` : undefined);
+
+  const marginTop = 8;
+  const marginRight = 8;
+  const marginBottom = 32;
+  const marginLeft = 40;
+
+  let measuredWidth = $state(400);
+  let rootElement = $state<HTMLElement>();
+
+  $effect(() => {
+    const element = rootElement;
+    if (!element) return;
+    // Guard for SSR / test environments without ResizeObserver.
+    if (typeof ResizeObserver === 'undefined') {
+      const rect = element.getBoundingClientRect();
+      if (rect.width > 0) measuredWidth = rect.width;
+      return;
+    }
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      // Ignore zero-width measurements (hidden / display:none) so the last good
+      // width is kept rather than collapsing the geometry, matching the fallback.
+      if (entry && entry.contentRect.width > 0) measuredWidth = entry.contentRect.width;
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  });
+
+  const plotWidth = $derived(Math.max(1, measuredWidth - marginLeft - marginRight));
+  const plotHeight = $derived(Math.max(1, height - marginTop - marginBottom));
+
+  const isEmpty = $derived(bins.length === 0);
+
+  // Spectrum magnitudes are linear non-negative. Coerce each bin's value to a
+  // finite, non-negative number so a stray NaN/Infinity/negative can't break the
+  // axis domain or invert bar geometry.
+  function sanitizeMagnitude(value: number): number {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  }
+
+  // Single-pass max over the sanitized magnitudes — NOT Math.max(...spread),
+  // which can overflow the argument limit on a very large bin array.
+  const maxValue = $derived.by(() => {
+    let max = 0;
+    for (const bin of bins) {
+      const magnitude = sanitizeMagnitude(bin.value);
+      if (magnitude > max) max = magnitude;
+    }
+    return max;
+  });
+
+  // Y-axis ticks (5 ticks from 0 to maxValue)
+  const tickCount = 5;
+  const yTicks = $derived.by(() => {
+    if (maxValue <= 0) return [0];
+    return Array.from({ length: tickCount }, (_, index) => (maxValue * index) / (tickCount - 1));
+  });
+
+  function scaleY(value: number): number {
+    if (maxValue <= 0) return plotHeight;
+    return plotHeight - (value / maxValue) * plotHeight;
+  }
+
+  const barWidth = $derived(bins.length > 0 ? plotWidth / bins.length : 0);
+
+  type SpectrumBar = {
+    x: number;
+    y: number;
+    barHeight: number;
+    barWidth: number;
+    label: string;
+    value: number;
+  };
+  const spectrumBars = $derived.by((): SpectrumBar[] => {
+    return bins.map((bin, index) => {
+      const magnitude = sanitizeMagnitude(bin.value);
+      // Scale against the real maxValue (with a zero guard) — NOT Math.max(maxValue, 1),
+      // which would prevent data whose max is < 1 from ever reaching the top tick.
+      const barHeight = maxValue > 0 ? (magnitude / maxValue) * plotHeight : 0;
+      return {
+        x: index * barWidth + 1,
+        y: plotHeight - barHeight,
+        barHeight,
+        barWidth: Math.max(1, barWidth - 2),
+        label: bin.label,
+        value: magnitude,
+      };
+    });
+  });
+
+  // Show only a subset of x-axis labels to avoid clutter
+  const maxXLabels = 8;
+  const xLabelStep = $derived(Math.max(1, Math.ceil(bins.length / maxXLabels)));
+
+  const hasDataTable = $derived(dataTableVisibility !== 'hidden');
+</script>
+
+<figure
+  {...rest}
+  bind:this={rootElement}
+  id={rootId}
+  class={classNames('cinder-spectrum-chart', customClassName)}
+  aria-label={label}
+  aria-describedby={descriptionId}
+>
+  {#if description}
+    <p id={descriptionId} class="cinder-spectrum-chart__description">{description}</p>
+  {/if}
+  <div
+    class="cinder-spectrum-chart__viewport"
+    style:height="{height}px"
+    data-cinder-loading={loading || undefined}
+  >
+    {#if loading}
+      <div class="cinder-spectrum-chart__state">
+        {#if loadingContent}{@render loadingContent()}{:else}Loading…{/if}
+      </div>
+    {:else if isEmpty}
+      <div class="cinder-spectrum-chart__state">
+        {#if empty}{@render empty()}{:else}No spectrum data{/if}
+      </div>
+    {/if}
+    <svg
+      role="img"
+      viewBox={`0 0 ${measuredWidth} ${height}`}
+      aria-hidden={loading || isEmpty ? 'true' : undefined}
+      aria-labelledby={!loading && !isEmpty ? `${rootId}-svg-title` : undefined}
+    >
+      {#if !loading && !isEmpty}
+        <title id="{rootId}-svg-title">{label}</title>
+      {/if}
+      <!-- Plot geometry only renders with data — otherwise the loading/empty
+           overlay would have a stray baseline grid line and ticks drawn under it
+           (yTicks falls back to [0] when there is no data). -->
+      {#if !loading && !isEmpty}
+        <g transform={`translate(${marginLeft}, ${marginTop})`}>
+          <!-- Y-axis ticks -->
+          {#each yTicks as tick, index (index)}
+            <text
+              class="cinder-spectrum-chart__tick-label"
+              x={-6}
+              y={scaleY(tick)}
+              text-anchor="end"
+              dominant-baseline="middle"
+              >{formatNumericValue(tick, undefined, undefined, { index })}</text
+            >
+            <line
+              class="cinder-spectrum-chart__grid-line"
+              x1="0"
+              x2={plotWidth}
+              y1={scaleY(tick)}
+              y2={scaleY(tick)}
+              aria-hidden="true"
+            />
+          {/each}
+          <!-- Frequency bars -->
+          {#each spectrumBars as bar, index (index)}
+            <rect
+              class="cinder-spectrum-chart__bar"
+              x={bar.x}
+              y={bar.y}
+              width={bar.barWidth}
+              height={bar.barHeight}
+              aria-hidden="true"
+              data-cinder-bin={bar.label}
+            />
+          {/each}
+          <!-- X-axis frequency labels (sampled to avoid overlap) -->
+          {#each spectrumBars as bar, index (index)}
+            {#if index % xLabelStep === 0}
+              <text
+                class="cinder-spectrum-chart__tick-label"
+                x={bar.x + bar.barWidth / 2}
+                y={plotHeight + 16}
+                text-anchor="middle"
+                dominant-baseline="auto">{bar.label}</text
+              >
+            {/if}
+          {/each}
+        </g>
+      {/if}
+    </svg>
+  </div>
+  {#if hasDataTable}
+    <table class={dataTableClass(dataTableVisibility)}>
+      <caption>{dataTableCaption ?? label}</caption>
+      <thead>
+        <tr>
+          <th scope="col">Frequency</th>
+          <th scope="col">Magnitude</th>
+        </tr>
+      </thead>
+      <tbody>
+        <!-- Keyed by index, not label: frequency-bin labels are not guaranteed unique. -->
+        {#each spectrumBars as bar, index (index)}
+          <tr>
+            <td>{bar.label}</td>
+            <td>{formatNumericValue(bar.value, undefined, undefined, { index })}</td>
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  {/if}
+</figure>

package/src/components/spectrum-chart/spectrum-chart.types.ts

@@ -0,0 +1,44 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ChartDataTableVisibility } from '../chart.types.ts';
+
+export type SpectrumBin = {
+  /** Frequency label, e.g. '440 Hz' or '1 kHz'. */
+  label: string;
+  /** Magnitude or power for this bin. Non-negative. */
+  value: number;
+};
+
+export type SpectrumChartProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Accessible label for the chart. Required for screen readers. */
+  label: string;
+  /** Optional description rendered below the label. */
+  description?: string;
+  /** Frequency bins with label + magnitude value. */
+  bins: SpectrumBin[];
+  /** Pixel height of the chart. Default `160`. */
+  height?: number;
+  /** Whether the chart is in a loading state. */
+  loading?: boolean;
+  /** Controls data table visibility. Default `screen-reader-only`. */
+  dataTableVisibility?: ChartDataTableVisibility;
+  /** Custom data table caption; falls back to `label`. */
+  dataTableCaption?: string;
+  /** Custom class applied to the root element. */
+  class?: string;
+  /** Snippet rendered when there are no bins. */
+  empty?: Snippet;
+  /** Snippet rendered while loading. */
+  loadingContent?: Snippet;
+};
+
+export type SpectrumChartSchemaProps = {
+  label: string;
+  description?: string;
+  bins: SpectrumBin[];
+  height?: number;
+  loading?: boolean;
+  dataTableVisibility?: ChartDataTableVisibility;
+  dataTableCaption?: string;
+  class?: string;
+};

package/src/components/spectrum-chart/spectrum-chart.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/spectrum-chart/spectrum-chart.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/status-dot/README.md

@@ -16,13 +16,13 @@ A semantic status indicator that pairs a colored dot with an accessible label.
 
 <!-- generated:props:start -->
 
-| Prop        | Type                                                                                | Required | Default | Description                                                                                              |
-| ----------- | ----------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
-| `class`     | `string`                                                                            | no       | —       | Extra classes appended to the root element.                                                              |
-| `label`     | `string`                                                                            | no       | —       | Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way. |
-| `showLabel` | `boolean`                                                                           | no       | `true`  | Whether to render the visible label.                                                                     |
-| `size`      | `"sm"` \| `"md"`                                                                    | no       | `"md"`  | Dot size.                                                                                                |
-| `status`    | `"online"` \| `"offline"` \| `"warning"` \| `"error"` \| `"pending"` \| `"neutral"` | yes      | —       | Required semantic status. Drives color via `data-cinder-status`.                                         |
+| Prop        | Type                                                                                                             | Required | Default | Description                                                                                                                                |
+| ----------- | ---------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`     | `string`                                                                                                         | no       | —       | Extra classes appended to the root element.                                                                                                |
+| `label`     | `string`                                                                                                         | no       | —       | Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way.                                   |
+| `showLabel` | `boolean`                                                                                                        | no       | `true`  | Whether to render the visible label.                                                                                                       |
+| `size`      | `"sm"` \| `"md"`                                                                                                 | no       | `"md"`  | Dot size.                                                                                                                                  |
+| `status`    | `"online"` \| `"offline"` \| `"warning"` \| `"error"` \| `"pending"` \| `"neutral"` \| `"success"` \| `"accent"` | yes      | —       | Required semantic status. Drives color via `data-cinder-status`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`. |
 
 <!-- generated:props:end -->
 

package/src/components/status-dot/status-dot.css

@@ -77,4 +77,12 @@
   .cinder-status-dot[data-cinder-status='neutral'] {
     --cinder-status-dot-color: var(--cinder-text-muted);
   }
+
+  .cinder-status-dot[data-cinder-status='success'] {
+    --cinder-status-dot-color: var(--cinder-success);
+  }
+
+  .cinder-status-dot[data-cinder-status='accent'] {
+    --cinder-status-dot-color: var(--cinder-accent);
+  }
 }

package/src/components/status-dot/status-dot.schema.json

@@ -3,8 +3,8 @@
   "type": "object",
   "properties": {
     "status": {
-      "enum": ["online", "offline", "warning", "error", "pending", "neutral"],
-      "description": "Required semantic status. Drives color via `data-cinder-status`."
+      "enum": ["online", "offline", "warning", "error", "pending", "neutral", "success", "accent"],
+      "description": "Required semantic status. Drives color via `data-cinder-status`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`."
     },
     "label": {
       "type": "string",

package/src/components/status-dot/status-dot.schema.ts

@@ -5,8 +5,9 @@ const schema = {
   type: 'object',
   properties: {
     status: {
-      enum: ['online', 'offline', 'warning', 'error', 'pending', 'neutral'],
-      description: 'Required semantic status. Drives color via `data-cinder-status`.',
+      enum: ['online', 'offline', 'warning', 'error', 'pending', 'neutral', 'success', 'accent'],
+      description:
+        'Required semantic status. Drives color via `data-cinder-status`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`.',
     },
     label: {
       type: 'string',

package/src/components/status-dot/status-dot.types.ts

@@ -9,10 +9,21 @@ import type { HTMLAttributes } from 'svelte/elements';
  * `error` → `--cinder-danger`) lives in `status-dot.css` so consumers can
  * theme without forking the component.
  *
+ * - `success` maps to `--cinder-success` (same hue as `online`).
+ * - `accent` maps to `--cinder-accent`.
+ *
  * Exported so host components (e.g. `stacked-list-item.svelte`) can type
  * their own `status` prop against this union rather than restating it.
  */
-export type StatusDotStatus = 'online' | 'offline' | 'warning' | 'error' | 'pending' | 'neutral';
+export type StatusDotStatus =
+  | 'online'
+  | 'offline'
+  | 'warning'
+  | 'error'
+  | 'pending'
+  | 'neutral'
+  | 'success'
+  | 'accent';
 
 export type StatusDotSize = 'sm' | 'md';
 
@@ -39,7 +50,7 @@ export type StatusDotProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
 };
 
 export interface StatusDotSchemaProps {
-  /** Required semantic status. Drives color via `data-cinder-status`. */
+  /** Required semantic status. Drives color via `data-cinder-status`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`. */
   status: StatusDotStatus;
   /** Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way. */
   label?: string;

package/src/components/subscription-badge/README.md

@@ -0,0 +1,50 @@
+# SubscriptionBadge
+
+Opinionated Badge variant that communicates billing subscription states with a standardized tone, icon, and human-readable label — never relying on color alone.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { SubscriptionBadge } from '@lostgradient/cinder/subscription-badge';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Displaying the billing state of a subscription in a dashboard, invoice list, or account settings page.
+- Annotating a plan name, customer row, or invoice line with its current payment lifecycle state.
+
+### Avoid When
+
+- The subscription state is not one of the six recognized values — use Badge directly with a custom label.
+- You need an interactive control that changes the state — use a Button or Select.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop    | Type                                                                                      | Required | Default | Description                                                                                       |
+| ------- | ----------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `class` | `string`                                                                                  | no       | —       | Extra classes forwarded to the underlying Badge.                                                  |
+| `state` | `"active"` \| `"trialing"` \| `"past-due"` \| `"canceled"` \| `"expired"` \| `"refunded"` | yes      | —       | The billing lifecycle state to display. Determines the badge tone, icon, and label automatically. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/subscription-badge/index.ts

@@ -0,0 +1,6 @@
+import './subscription-badge.css';
+import SubscriptionBadge from './subscription-badge.svelte';
+
+export default SubscriptionBadge;
+export type { SubscriptionBadgeProps, SubscriptionState } from './subscription-badge.types.ts';
+export { SubscriptionBadge };

package/src/components/subscription-badge/subscription-badge.css

@@ -0,0 +1,18 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  /* ========================================
+ * SUBSCRIPTION BADGE
+ *
+ * Thin wrapper over .cinder-badge that identifies subscription-state
+ * badge instances in the DOM. All visual styling (tone, size, layout)
+ * is inherited from Badge — this rule exists only to give the component
+ * a stable CSS anchor for host-application overrides and for the
+ * component graph invariant check that every component has a CSS entry.
+ * ======================================== */
+
+  .cinder-subscription-badge {
+    /* No additional overrides needed — Badge tones cover all six states.
+     * Host applications can target .cinder-subscription-badge to further
+     * customize without touching the base Badge rules. */
+  }
+}

package/src/components/subscription-badge/subscription-badge.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "subscription-badge",
+  "import": "@lostgradient/cinder/subscription-badge",
+  "examples": [
+    {
+      "id": "all-states",
+      "title": "Subscription badge states",
+      "description": "All six billing lifecycle states, each with a distinct icon, label, and tone.",
+      "code": "<script lang=\"ts\">\n  import { SubscriptionBadge } from '@lostgradient/cinder/subscription-badge';\n</script>\n\n<div class=\"example-preview-row\">\n  <SubscriptionBadge state=\"active\" />\n  <SubscriptionBadge state=\"trialing\" />\n  <SubscriptionBadge state=\"past-due\" />\n  <SubscriptionBadge state=\"canceled\" />\n  <SubscriptionBadge state=\"expired\" />\n  <SubscriptionBadge state=\"refunded\" />\n</div>\n"
+    },
+    {
+      "id": "in-context",
+      "title": "Subscription badge in context",
+      "description": "SubscriptionBadge shown alongside plan details inside a Card, representing typical dashboard usage.",
+      "code": "<script lang=\"ts\">\n  import { Card } from '@lostgradient/cinder/card';\n  import { SubscriptionBadge } from '@lostgradient/cinder/subscription-badge';\n\n  const plans = [\n    { name: 'Pro — Monthly', state: 'active' },\n    { name: 'Team — Annual', state: 'trialing' },\n    { name: 'Starter — Monthly', state: 'past-due' },\n    { name: 'Enterprise', state: 'canceled' },\n  ] as const;\n</script>\n\n<div class=\"example-preview-column\">\n  {#each plans as plan (plan.name)}\n    <Card>\n      <div style=\"display: flex; align-items: center; justify-content: space-between; gap: 1rem;\">\n        <span style=\"font-size: var(--cinder-text-sm); color: var(--cinder-text);\">{plan.name}</span\n        >\n        <SubscriptionBadge state={plan.state} />\n      </div>\n    </Card>\n  {/each}\n</div>\n"
+    }
+  ]
+}

package/src/components/subscription-badge/subscription-badge.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "state": {
+      "enum": ["active", "trialing", "past-due", "canceled", "expired", "refunded"],
+      "description": "The billing lifecycle state to display.\nDetermines the badge tone, icon, and label automatically."
+    },
+    "class": {
+      "type": "string",
+      "description": "Extra classes forwarded to the underlying Badge."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["state"]
+}

package/src/components/subscription-badge/subscription-badge.schema.ts

@@ -0,0 +1,21 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    state: {
+      enum: ['active', 'trialing', 'past-due', 'canceled', 'expired', 'refunded'],
+      description:
+        'The billing lifecycle state to display.\nDetermines the badge tone, icon, and label automatically.',
+    },
+    class: {
+      type: 'string',
+      description: 'Extra classes forwarded to the underlying Badge.',
+    },
+  },
+  additionalProperties: false,
+  required: ['state'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/subscription-badge/subscription-badge.svelte

@@ -0,0 +1,69 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status alpha
+   * @purpose Opinionated Badge variant that communicates billing subscription states with a standardized tone, icon, and human-readable label.
+   * @tag billing
+   * @tag subscription
+   * @tag status
+   * @useWhen Displaying the billing state of a subscription in a dashboard, invoice list, or account settings page.
+   * @useWhen Annotating a plan name, customer row, or invoice line with its current payment lifecycle state.
+   * @avoidWhen The subscription state is not one of the six recognized values — use Badge directly with a custom label instead.
+   * @avoidWhen You need an interactive control that lets users change the state — use a Button or Select.
+   * @related badge, status-dot, chip
+   */
+  export type { SubscriptionBadgeProps, SubscriptionState } from './subscription-badge.types.ts';
+</script>
+
+<script lang="ts">
+  import CircleCheck from 'lucide-svelte/icons/circle-check';
+  import Clock from 'lucide-svelte/icons/clock';
+  import TriangleAlert from 'lucide-svelte/icons/triangle-alert';
+  import CircleX from 'lucide-svelte/icons/circle-x';
+  import CalendarX from 'lucide-svelte/icons/calendar-x';
+  import RotateCcw from 'lucide-svelte/icons/rotate-ccw';
+
+  import Badge from '../badge/badge.svelte';
+  import type { BadgeVariant } from '../badge/badge.types.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { SubscriptionBadgeProps, SubscriptionState } from './subscription-badge.types.ts';
+
+  // lucide-svelte ships its icons as Svelte component classes. Every lucide icon
+  // shares one signature, so the config types its icon field as the type of a
+  // single concrete icon rather than the Svelte 5 `Component` functional type,
+  // which does not structurally match the class export under svelte-check.
+  type IconComponent = typeof CircleCheck;
+
+  interface StateConfig {
+    tone: BadgeVariant;
+    icon: IconComponent;
+    label: string;
+  }
+
+  const STATE_CONFIG: Record<SubscriptionState, StateConfig> = {
+    active: { tone: 'success', icon: CircleCheck, label: 'Active' },
+    trialing: { tone: 'info', icon: Clock, label: 'Trialing' },
+    'past-due': { tone: 'warning', icon: TriangleAlert, label: 'Past due' },
+    canceled: { tone: 'neutral', icon: CircleX, label: 'Canceled' },
+    expired: { tone: 'danger', icon: CalendarX, label: 'Expired' },
+    refunded: { tone: 'info', icon: RotateCcw, label: 'Refunded' },
+  };
+
+  let { state, class: customClassName, ...rest }: SubscriptionBadgeProps = $props();
+
+  const config = $derived(STATE_CONFIG[state]);
+  const Icon = $derived(config.icon);
+  const label = $derived(config.label);
+  const tone = $derived(config.tone);
+</script>
+
+<Badge
+  variant={tone}
+  class={classNames('cinder-subscription-badge', customClassName)}
+  data-cinder-state={state}
+  {...rest}
+>
+  <Icon class="icon-sm" aria-hidden="true" />
+  {label}
+</Badge>

package/src/components/subscription-badge/subscription-badge.types.ts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/**
+ * Billing lifecycle states for a subscription.
+ *
+ * Each value is stamped onto the root element as `data-cinder-state` and
+ * maps to a Badge tone and an icon in `subscription-badge.svelte`. Color is
+ * NOT the only differentiator — every state also carries a visible text label
+ * and an icon so the state is conveyed even to users who cannot distinguish
+ * colors (WCAG 1.4.1).
+ */
+export type SubscriptionState =
+  | 'active'
+  | 'trialing'
+  | 'past-due'
+  | 'canceled'
+  | 'expired'
+  | 'refunded';
+
+/** Props for the SubscriptionBadge component. */
+export type SubscriptionBadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children'> & {
+  /** The billing lifecycle state to display. */
+  state: SubscriptionState;
+  /** Extra classes forwarded to the underlying Badge. */
+  class?: string;
+};
+
+/** Cinder-specific props for the SubscriptionBadge component, used by the schema generator. */
+export interface SubscriptionBadgeSchemaProps {
+  /**
+   * The billing lifecycle state to display.
+   * Determines the badge tone, icon, and label automatically.
+   */
+  state: SubscriptionState;
+  /** Extra classes forwarded to the underlying Badge. */
+  class?: string;
+}

package/src/components/subscription-badge/subscription-badge.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/subscription-badge/subscription-badge.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;