@lilydesignsystem/svelte-headless 0.1.0

package/dist/components/DoList/DoList.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+    // DoList component
+    //
+    // A list of recommended actions or best practices. Renders as a <ol> with
+    // role="list" and an accessible label. Used in design system documentation,
+    // guidelines, and instructional content to communicate what users should do.
+    // Paired with DontList to create do/don't guidance patterns.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, default "Do". Accessible name for the list.
+    //   children — Snippet, required. List items, each should be an <li> element.
+    //   ...restProps — additional HTML attributes spread onto the <ol> element.
+    //
+    // Syntax:
+    //   <DoList><li>Best practice</li></DoList>
+    //
+    // Examples:
+    //   <!-- Basic do list -->
+    //   <DoList>
+    //     <li>Write clear labels</li>
+    //     <li>Use semantic HTML</li>
+    //   </DoList>
+    //
+    //   <!-- Custom label for internationalization -->
+    //   <DoList label="Recommended">
+    //     <li>Provide alt text for images</li>
+    //     <li>Use sufficient color contrast</li>
+    //   </DoList>
+    //
+    // Keyboard:
+    //   - None — passive container for list items
+    //
+    // Accessibility:
+    //   - role="list" preserves list semantics even when CSS removes default styling
+    //   - aria-label provides an accessible name (defaults to "Do")
+    //
+    // Internationalization:
+    //   - The label prop defaults to "Do" but can be overridden for any locale
+    //   - All list item text comes through consumer-provided children
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Companion to DontList; typically used together
+    //
+    // References:
+    //   - MDN ul element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul
+    //   - WAI list role: https://www.w3.org/WAI/ARIA/apd/roles/list/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = "Do",
+        children,
+        ...restProps
+    }: {
+        /** Accessible name for the list. */
+        label?: string;
+        /** List items. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DoList.svelte -->
+<ul
+    class={`do-list ${className}`}
+    role="list"
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</ul>

package/dist/components/DoList/DoList.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible name for the list. */
+    label?: string;
+    /** List items. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const DoList: import("svelte").Component<$$ComponentProps, {}, "">;
+type DoList = ReturnType<typeof DoList>;
+export default DoList;

package/dist/components/DoListItem/DoListItem.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+    // DoListItem component
+    //
+    // A single recommended-practice item within a "Do" list. Renders a semantic
+    // <li> element representing a guideline or best practice that users should
+    // follow. Commonly used in design system documentation, style guides, and
+    // instructional content to show approved patterns alongside DontListItem.
+    //
+    // The component sets data-recommendation="do" for consumer styling hooks,
+    // enabling visual differentiation (e.g. green checkmarks, success borders)
+    // without embedding any styles itself.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   children — Snippet, required. The recommendation content.
+    //   ...restProps — additional HTML attributes spread onto the <li>.
+    //
+    // Syntax:
+    //   <DoListItem>Use semantic HTML elements</DoListItem>
+    //
+    // Examples:
+    //   <!-- Design system guideline list -->
+    //   <ul aria-label="Recommended practices">
+    //     <DoListItem>Use descriptive alt text for images</DoListItem>
+    //     <DoListItem>Provide visible focus indicators</DoListItem>
+    //     <DoListItem>Use sufficient color contrast</DoListItem>
+    //   </ul>
+    //
+    //   <!-- Side-by-side do/don't pattern -->
+    //   <ul aria-label="Do">
+    //     <DoListItem>Write clear error messages</DoListItem>
+    //   </ul>
+    //   <ul aria-label="Don't">
+    //     <DontListItem>Use technical jargon in errors</DontListItem>
+    //   </ul>
+    //
+    // Keyboard:
+    //   - None directly — passive informational display, not interactive
+    //
+    // Accessibility:
+    //   - Semantic <li> element provides list item semantics within the parent list
+    //   - Screen readers announce list position from the parent <ul> or <ol>
+    //   - data-recommendation attribute provides a hook for consumer styling
+    //
+    // Internationalization:
+    //   - All content is provided through the children snippet
+    //   - No hardcoded strings in the component
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Should be placed inside a <ul> or <ol> for valid HTML
+    //   - Consumer can target [data-recommendation="do"] for visual styling
+    //
+    // References:
+    //   - MDN li element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+    //   - Material Design Do/Don't guidelines: https://m3.material.io/foundations/content-design/style-guide/overview
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: {
+        /** The recommendation content. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DoListItem.svelte -->
+<li
+    class={`do-list-item ${className}`}
+    data-recommendation="do"
+    {...restProps}
+>
+    {@render children?.()}
+</li>

package/dist/components/DoListItem/DoListItem.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** The recommendation content. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const DoListItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type DoListItem = ReturnType<typeof DoListItem>;
+export default DoListItem;

package/dist/components/DocumentList/DocumentList.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = undefined,
+        children,
+        ...restProps
+    }: {
+        label?: string;
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DocumentList.svelte -->
+<ul
+    class={`document-list ${className}`}
+
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</ul>

package/dist/components/DocumentList/DocumentList.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    label?: string;
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const DocumentList: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocumentList = ReturnType<typeof DocumentList>;
+export default DocumentList;

package/dist/components/DocumentListItem/DocumentListItem.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = undefined,
+        children,
+        ...restProps
+    }: {
+        label?: string;
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DocumentListItem.svelte -->
+<li
+    class={`document-list-item ${className}`}
+
+
+    {...restProps}
+>
+    {@render children?.()}
+</li>

package/dist/components/DocumentListItem/DocumentListItem.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    label?: string;
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const DocumentListItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocumentListItem = ReturnType<typeof DocumentListItem>;
+export default DocumentListItem;

package/dist/components/DontList/DontList.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+    // DontList component
+    //
+    // A list of discouraged actions or practices to avoid. Renders as a <ol> with
+    // role="list" and an accessible label. Used in design system documentation,
+    // guidelines, and instructional content to communicate what users should not do.
+    // Paired with DoList to create do/don't guidance patterns.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, default "Don't". Accessible name for the list.
+    //   children — Snippet, required. List items, each should be an <li> element.
+    //   ...restProps — additional HTML attributes spread onto the <ol> element.
+    //
+    // Syntax:
+    //   <DontList><li>Avoid this</li></DontList>
+    //
+    // Examples:
+    //   <!-- Basic don't list -->
+    //   <DontList>
+    //     <li>Skip alt text</li>
+    //     <li>Use only color for meaning</li>
+    //   </DontList>
+    //
+    //   <!-- Custom label for internationalization -->
+    //   <DontList label="Avoid">
+    //     <li>Hard-code user-facing strings</li>
+    //     <li>Rely on placeholder text as labels</li>
+    //   </DontList>
+    //
+    // Keyboard:
+    //   - None — passive container for list items
+    //
+    // Accessibility:
+    //   - role="list" preserves list semantics even when CSS removes default styling
+    //   - aria-label provides an accessible name (defaults to "Don't")
+    //
+    // Internationalization:
+    //   - The label prop defaults to "Don't" but can be overridden for any locale
+    //   - All list item text comes through consumer-provided children
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Companion to DoList; typically used together
+    //
+    // References:
+    //   - MDN ul element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul
+    //   - WAI list role: https://www.w3.org/WAI/ARIA/apd/roles/list/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = "Don't",
+        children,
+        ...restProps
+    }: {
+        /** Accessible name for the list. */
+        label?: string;
+        /** List items. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DontList.svelte -->
+<ul
+    class={`dont-list ${className}`}
+    role="list"
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</ul>

package/dist/components/DontList/DontList.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible name for the list. */
+    label?: string;
+    /** List items. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const DontList: import("svelte").Component<$$ComponentProps, {}, "">;
+type DontList = ReturnType<typeof DontList>;
+export default DontList;

package/dist/components/DontListItem/DontListItem.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+    // DontListItem component
+    //
+    // A single discouraged-practice item within a "Don't" list. Renders a semantic
+    // <li> element representing a guideline or practice that users should avoid.
+    // Commonly used in design system documentation, style guides, and instructional
+    // content to show anti-patterns alongside DoListItem.
+    //
+    // The component sets data-recommendation="dont" for consumer styling hooks,
+    // enabling visual differentiation (e.g. red crosses, danger borders) without
+    // embedding any styles itself.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   children — Snippet, required. The discouraged-practice content.
+    //   ...restProps — additional HTML attributes spread onto the <li>.
+    //
+    // Syntax:
+    //   <DontListItem>Use vague placeholder text</DontListItem>
+    //
+    // Examples:
+    //   <!-- Design system anti-pattern list -->
+    //   <ul aria-label="Practices to avoid">
+    //     <DontListItem>Use color alone to convey meaning</DontListItem>
+    //     <DontListItem>Remove focus outlines without replacement</DontListItem>
+    //     <DontListItem>Rely solely on placeholder text as labels</DontListItem>
+    //   </ul>
+    //
+    //   <!-- Side-by-side do/don't pattern -->
+    //   <ul aria-label="Do">
+    //     <DoListItem>Write clear error messages</DoListItem>
+    //   </ul>
+    //   <ul aria-label="Don't">
+    //     <DontListItem>Use technical jargon in errors</DontListItem>
+    //   </ul>
+    //
+    // Keyboard:
+    //   - None directly — passive informational display, not interactive
+    //
+    // Accessibility:
+    //   - Semantic <li> element provides list item semantics within the parent list
+    //   - Screen readers announce list position from the parent <ul> or <ol>
+    //   - data-recommendation attribute provides a hook for consumer styling
+    //
+    // Internationalization:
+    //   - All content is provided through the children snippet
+    //   - No hardcoded strings in the component
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Should be placed inside a <ul> or <ol> for valid HTML
+    //   - Consumer can target [data-recommendation="dont"] for visual styling
+    //
+    // References:
+    //   - MDN li element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+    //   - Material Design Do/Don't guidelines: https://m3.material.io/foundations/content-design/style-guide/overview
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: {
+        /** The discouraged-practice content. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DontListItem.svelte -->
+<li
+    class={`dont-list-item ${className}`}
+    data-recommendation="dont"
+    {...restProps}
+>
+    {@render children?.()}
+</li>

package/dist/components/DontListItem/DontListItem.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** The discouraged-practice content. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const DontListItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type DontListItem = ReturnType<typeof DontListItem>;
+export default DontListItem;

package/dist/components/DownloadButton/DownloadButton.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+    // DownloadButton component
+    //
+    // A download link styled as a button, with optional file size and format
+    // metadata. Renders a native <a> element so consumers can right-click and
+    // save. Both `href` and `label` are required: the label provides the
+    // accessible name and a default visible text fallback.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   href — string, REQUIRED. File URL.
+    //   label — string, REQUIRED. Accessible label and default text.
+    //   fileSize — string, optional. Pre-formatted file size text e.g. "2.4 MB".
+    //   fileFormat — string, optional. File format text e.g. "PDF".
+    //   download — string | boolean, optional. Native download attribute.
+    //   children — Snippet, optional. Custom button content.
+    //   ...restProps — additional HTML attributes spread onto the <a>.
+    //
+    // Syntax:
+    //   <DownloadButton href="/file.pdf" label="Download brochure" fileSize="2.4 MB" fileFormat="PDF" download />
+    //
+    // Accessibility:
+    //   - Implicit link semantics
+    //   - aria-label provides descriptive name including download intent
+    //
+    // Internationalization:
+    //   - Label and content come through props
+    //
+    // Claude rules:
+    //   - Headless: no styles
+    //   - href and label are REQUIRED — TypeScript reflects this
+    //
+    // References:
+    //   - HTML download attribute: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        href,
+        label,
+        fileSize = undefined,
+        fileFormat = undefined,
+        download = undefined,
+        children = undefined,
+        ...restProps
+    }: {
+        /** Consumer CSS class appended to base class */
+        class?: string;
+        /** File URL (REQUIRED) */
+        href: string;
+        /** Accessible label and default visible text (REQUIRED) */
+        label: string;
+        /** Pre-formatted file size text */
+        fileSize?: string;
+        /** File format text */
+        fileFormat?: string;
+        /** Native download attribute */
+        download?: string | boolean;
+        /** Custom button content (defaults to label) */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- DownloadButton.svelte -->
+<a
+    class={`download-button ${className}`}
+    {href}
+    aria-label={label}
+    data-file-size={fileSize}
+    data-file-format={fileFormat}
+    download={download === true ? "" : download}
+    {...restProps}
+>
+    {#if children}{@render children?.()}{:else}{label}{/if}
+</a>

package/dist/components/DownloadButton/DownloadButton.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Consumer CSS class appended to base class */
+    class?: string;
+    /** File URL (REQUIRED) */
+    href: string;
+    /** Accessible label and default visible text (REQUIRED) */
+    label: string;
+    /** Pre-formatted file size text */
+    fileSize?: string;
+    /** File format text */
+    fileFormat?: string;
+    /** Native download attribute */
+    download?: string | boolean;
+    /** Custom button content (defaults to label) */
+    children?: Snippet;
+    [key: string]: unknown;
+};
+declare const DownloadButton: import("svelte").Component<$$ComponentProps, {}, "">;
+type DownloadButton = ReturnType<typeof DownloadButton>;
+export default DownloadButton;

package/dist/components/Draft/Draft.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    let {
+        class: className = "",
+        label = undefined,
+        status = undefined,
+        children,
+        ...restProps
+    }: {
+        label?: string;
+        status?: string;
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- Draft.svelte -->
+<div
+    class={`draft ${className}`}
+    aria-label={label}
+    data-status={status}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

package/dist/components/Draft/Draft.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    label?: string;
+    status?: string;
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const Draft: import("svelte").Component<$$ComponentProps, {}, "">;
+type Draft = ReturnType<typeof Draft>;
+export default Draft;

package/dist/components/Drawer/Drawer.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+    // Drawer component
+    //
+    // A panel that slides in from an edge of the viewport, typically used for
+    // navigation menus, filters, or supplementary content. Renders conditionally
+    // based on the open state and uses role="dialog" with aria-modal="true" for
+    // proper screen reader behavior. The side prop indicates which edge via a
+    // data-side attribute for consumer positioning and animation styles.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   open — boolean, default false. Whether the drawer is visible; bindable.
+    //   label — string, required. Accessible name for the drawer.
+    //   side — "left" | "right" | "top" | "bottom", default "left". Edge the drawer enters from.
+    //   children — Snippet, required. Drawer content.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <Drawer label="Nav" bind:open side="left">Content</Drawer>
+    //
+    // Examples:
+    //   <!-- Navigation drawer from left -->
+    //   <Drawer label="Navigation" bind:open side="left">
+    //     <nav>...</nav>
+    //   </Drawer>
+    //
+    //   <!-- Filters drawer from right -->
+    //   <Drawer label="Filters" bind:open={showFilters} side="right">
+    //     <form>...</form>
+    //   </Drawer>
+    //
+    // Keyboard:
+    //   - Escape: closes the drawer by setting open to false
+    //
+    // Accessibility:
+    //   - role="dialog" identifies the drawer as a dialog
+    //   - aria-label provides the accessible name
+    //   - aria-modal="true" indicates the drawer is modal
+    //   - tabindex="-1" allows programmatic focus management
+    //   - data-side attribute conveys position for consumer styling
+    //
+    // Internationalization:
+    //   - The label prop accepts any string; consumers provide localized text
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses $bindable() on open for two-way state binding
+    //   - Drawer is removed from DOM when open is false
+    //   - Consumer uses data-side for positioning CSS
+    //
+    // References:
+    //   - WAI-ARIA Dialog Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        open = $bindable(false),
+        label,
+        side = "left",
+        children,
+        ...restProps
+    }: {
+        /** Whether the drawer is visible. Bindable. */
+        open?: boolean;
+        /** Accessible name for the drawer. */
+        label: string;
+        /** Edge the drawer enters from. */
+        side?: "left" | "right" | "top" | "bottom";
+        /** Drawer content. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+
+    function onkeydown(event: KeyboardEvent) {
+        if (event.key === "Escape") {
+            event.preventDefault();
+            open = false;
+        }
+    }
+</script>
+
+{#if open}
+    <!-- Drawer.svelte -->
+    <div
+        class={`drawer ${className}`}
+        role="dialog"
+        tabindex="-1"
+        aria-label={label}
+        aria-modal="true"
+        data-side={side}
+        {onkeydown}
+        {...restProps}
+    >
+        {@render children?.()}
+    </div>
+{/if}