Merge branch 'next' into llms-txt

cspell.json

@@ -115,6 +115,9 @@
     "listbox",
     "listitem",
     "litelement",
+    "llm",
+    "llms",
+    "llmstxt",
     "longform",
     "lowercasing",
     "Lucide",

package-lock.json

@@ -14040,6 +14040,7 @@
         "@wc-toolkit/jsx-types": "^1.3.0",
         "eleventy-plugin-git-commit-date": "^0.1.3",
         "esbuild": "^0.25.11",
+        "gray-matter": "^4.0.3",
         "npm-check-updates": "^19.1.2"
       },
       "engines": {

packages/webawesome/custom-elements-manifest.js

@@ -7,6 +7,7 @@ import fs from 'fs';
 import * as path from 'node:path';
 import { pascalCase } from 'pascal-case';
 import * as url from 'url';
+import { llmsTxtPlugin } from './scripts/llms.js';
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 
 const packageData = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
@@ -188,6 +189,13 @@ export default {
       },
     }),
 
+    // Generate llms.txt
+    llmsTxtPlugin({
+      outdir,
+      docsDir: path.join(__dirname, 'docs'),
+      baseUrl: 'https://webawesome.com',
+    }),
+
     //
     // TODO - figure out why this broke when events were updated
     //

packages/webawesome/docs/_includes/sidebar.njk

@@ -29,8 +29,12 @@
   <li><a href="/docs/resources/contributing">Contributing</a></li>
   <li><a href="/docs/resources/changelog">Changelog</a></li>
   <li><a href="/docs/resources/visual-tests">Visual Tests</a></li>
-
-
+  <li>
+    <a class="wa-cluster wa-gap-xs" href="/docs/resources/llms">
+      LLMs
+      <wa-icon name="flask" aria-hidden="true" class="icon-shrink"></wa-icon>
+    </a>
+  </li>
 </ul>
 
 <!-- Components -->

packages/webawesome/docs/docs/resources/changelog.md

@@ -13,6 +13,7 @@ Components with the <wa-badge variant="warning">Experimental</wa-badge> badge sh
 
 ## Next
 
+- Added llms.txt to assist AI agents with using Web Awesome [discuss:1100]
 - Added `justify-content` CSS utilities [pr:1930]
 - Added missing `.wa-gap-4xl` utility class [pr:1931]
 - Added `pointercancel` and `touchcancel` event handling to draggable elements to prevent drags from getting stuck

packages/webawesome/docs/docs/resources/llms.md

@@ -0,0 +1,86 @@
+---
+title: LLMs
+description: Web Awesome provides an llms.txt file to help AI assistants understand and work with our components.
+layout: page-outline
+---
+
+The [llms.txt specification](https://llmstxt.org/) is a proposed standard for providing information to large language models (LLMs) in a format they can easily consume. It's like a robots.txt, but instead of telling search engines how to crawl your site, it helps AI assistants understand your project.
+
+Web Awesome publishes an `llms.txt` file that provides AI tools with structured information about our components, including their APIs, properties, events, methods, slots, and CSS custom properties.
+
+:::warning
+This feature is experimental! The llms.txt format and its contents may change as we refine the output based on feedback and evolving AI capabilities.
+:::
+
+## Why Use It?
+
+When working with AI coding assistants like Claude, ChatGPT, Copilot, or Cursor, you can reference the llms.txt file to give the AI context about Web Awesome components. This can lead to more accurate code suggestions and fewer hallucinations when the AI generates Web Awesome code.
+
+## Accessing the File
+
+The llms.txt file is available in every Web Awesome build at:
+
+```
+/dist/llms.txt
+/dist-cdn/llms.txt
+```
+
+You can also find it in your `node_modules` directory if you've installed Web Awesome via npm:
+
+```
+node_modules/@awesome.me/webawesome/dist/llms.txt
+```
+
+## How to Use It
+
+How you reference the file depends on which AI tool you're using.
+
+### Claude Projects
+
+If you're using [Claude Projects](https://www.anthropic.com/news/projects), you can add the llms.txt URL to your project knowledge. Claude will use this context when helping you write Web Awesome code.
+
+### Cursor
+
+In [Cursor](https://cursor.sh/), you can add the file to your project's documentation sources via **Cursor Settings > Features > Docs**. You can also reference the file directly in chat using `@Docs` after adding it, or paste the content into the chat context.
+
+### VS Code + Copilot
+
+GitHub Copilot in VS Code doesn't have a built-in way to reference external documentation files, but you can:
+
+1. Copy the llms.txt file into your project's root directory
+2. Open it in a VS Code tab (Copilot considers open files as context)
+3. Use `#file` in Copilot Chat to explicitly reference it (e.g., `#file:llms.txt how do I create a dialog?`)
+
+### VS Code + Claude Code
+
+If you're using the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code), you can reference the file directly by path:
+
+```
+@node_modules/@awesome.me/webawesome/dist/llms.txt
+```
+
+Or simply ask Claude to read it — Claude Code can access files in your project directly.
+
+### Other AI Tools
+
+Most AI coding assistants allow you to provide context through URLs, file uploads, or direct pasting. Check your tool's documentation for the best way to include external references.
+
+## What's Included
+
+The llms.txt file contains:
+
+- An overview of Web Awesome and its capabilities
+- Links to documentation sections
+- A complete list of all components with descriptions
+- Detailed API reference for each component including:
+  - Slots
+  - Properties and their types
+  - Methods and their signatures
+  - Events
+  - CSS custom properties
+  - CSS parts
+  - CSS states
+
+## Feedback
+
+Since this is experimental, we'd love to hear how it works for you! If you find issues with the generated content or have suggestions for improvement, please [open an issue on GitHub](https://github.com/shoelace-style/webawesome/issues).

packages/webawesome/package.json

@@ -92,6 +92,7 @@
     "@wc-toolkit/jsx-types": "^1.3.0",
     "eleventy-plugin-git-commit-date": "^0.1.3",
     "esbuild": "^0.25.11",
+    "gray-matter": "^4.0.3",
     "npm-check-updates": "^19.1.2"
   }
 }

packages/webawesome/scripts/llms.js

@@ -0,0 +1,257 @@
+import fs from 'fs';
+import matter from 'gray-matter';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getAllComponents } from './shared.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Removes newlines from text to keep llms.txt formatting clean. */
+function removeNewlines(str) {
+  return str ? str.replace(/\n/g, ' ').trim() : '';
+}
+
+/** Loads front-matter from all component markdown files. */
+function loadAllFrontMatter(components, docsDir) {
+  const cache = new Map();
+
+  for (const component of components) {
+    const componentName = component.tagName.replace(/^wa-/, '');
+    const mdPath = path.join(docsDir, 'docs/components', `${componentName}.md`);
+
+    if (fs.existsSync(mdPath)) {
+      try {
+        const content = fs.readFileSync(mdPath, 'utf-8');
+        const { data } = matter(content);
+        cache.set(component.tagName, data);
+      } catch {
+        // Skip if parsing fails
+      }
+    }
+  }
+
+  return cache;
+}
+
+/** Generates the API reference section for a single component. */
+function generateComponentApiSection(component, frontMatterCache, baseUrl) {
+  const lines = [];
+  const frontMatter = frontMatterCache.get(component.tagName);
+  const componentSlug = component.tagName.replace(/^wa-/, '');
+  const description = removeNewlines(frontMatter?.description || component.summary || '');
+
+  lines.push(`#### \`<${component.tagName}>\``);
+  lines.push('');
+  lines.push(`**Description:** ${description || 'No description available.'}`);
+  lines.push('');
+  lines.push(`**Documentation:** ${baseUrl}/docs/components/${componentSlug}`);
+  lines.push('');
+
+  // Slots
+  if (component.slots?.length > 0) {
+    lines.push('**Slots:**');
+    lines.push('');
+    for (const slot of component.slots) {
+      const slotName = slot.name || '(default)';
+      lines.push(`- \`${slotName}\`: ${removeNewlines(slot.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // Properties
+  const properties =
+    component.members?.filter(m => m.kind === 'field' && m.privacy !== 'private' && m.description) || [];
+
+  if (properties.length > 0) {
+    lines.push('**Properties:**');
+    lines.push('');
+    for (const prop of properties) {
+      // Find corresponding attribute if any
+      const attr = component.attributes?.find(a => a.fieldName === prop.name);
+      const attrNote = attr && attr.name !== prop.name ? ` (attribute: \`${attr.name}\`)` : '';
+      const typeStr = prop.type?.text ? `Type: \`${removeNewlines(prop.type.text)}\`` : '';
+      const defaultStr = prop.default ? `Default: \`${prop.default}\`` : '';
+      const meta = [typeStr, defaultStr].filter(Boolean).join(', ');
+
+      lines.push(
+        `- \`${prop.name}\`${attrNote}: ${removeNewlines(prop.description) || 'No description.'}${meta ? ` (${meta})` : ''}`,
+      );
+    }
+    lines.push('');
+  }
+
+  // Methods
+  const methods = component.members?.filter(m => m.kind === 'method' && m.privacy !== 'private' && m.description) || [];
+
+  if (methods.length > 0) {
+    lines.push('**Methods:**');
+    lines.push('');
+    for (const method of methods) {
+      const params = method.parameters?.length
+        ? `(${method.parameters.map(p => `${p.name}: ${removeNewlines(p.type?.text) || 'unknown'}`).join(', ')})`
+        : '()';
+      lines.push(`- \`${method.name}${params}\`: ${removeNewlines(method.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // Events
+  const events = component.events?.filter(e => e.name) || [];
+  if (events.length > 0) {
+    lines.push('**Events:**');
+    lines.push('');
+    for (const event of events) {
+      lines.push(`- \`${event.name}\`: ${removeNewlines(event.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // CSS Custom Properties
+  if (component.cssProperties?.length > 0) {
+    lines.push('**CSS Custom Properties:**');
+    lines.push('');
+    for (const prop of component.cssProperties) {
+      const defaultStr = prop.default ? ` (Default: \`${prop.default}\`)` : '';
+      lines.push(`- \`${prop.name}\`: ${removeNewlines(prop.description) || 'No description.'}${defaultStr}`);
+    }
+    lines.push('');
+  }
+
+  // CSS Parts
+  if (component.cssParts?.length > 0) {
+    lines.push('**CSS Parts:**');
+    lines.push('');
+    for (const part of component.cssParts) {
+      lines.push(`- \`${part.name}\`: ${removeNewlines(part.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // CSS States
+  if (component.cssStates?.length > 0) {
+    lines.push('**CSS States:**');
+    lines.push('');
+    for (const state of component.cssStates) {
+      lines.push(`- \`${state.name}\`: ${removeNewlines(state.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  return lines;
+}
+
+/**
+ * Generates the complete llms.txt content.
+ */
+function generateLlmsTxt({ components, packageData, frontMatterCache, baseUrl }) {
+  const lines = [];
+
+  // H1 Title (required by llmstxt.org spec)
+  lines.push('# Web Awesome');
+  lines.push('');
+
+  // Blockquote summary
+  lines.push(`> ${packageData.description} Version ${packageData.version}.`);
+  lines.push('');
+
+  // Overview section
+  lines.push(
+    `
+Web Awesome provides a comprehensive set of customizable, accessible web components for building modern
+web applications. All components use shadow DOM and are framework-agnostic, working with vanilla JavaScript
+or any framework including React, Vue, Angular, and Svelte.
+
+Form controls are form-associated custom elements that work with native form validation and the
+Constraint Validation API.
+
+Font Awesome is the default icon library, so \`<wa-icon name="...">\` values should reference Font Awesome
+icon names.
+`.trim(),
+  );
+  lines.push('');
+
+  //
+  // Documentation
+  //
+  lines.push('## Documentation');
+  lines.push('');
+  lines.push(`For comprehensive documentation, visit ${baseUrl}/docs/`);
+  lines.push('');
+  lines.push(`- [Getting Started](${baseUrl}/docs/getting-started): Installation and setup guide`);
+  lines.push(`- [Components Overview](${baseUrl}/docs/components): Complete component reference`);
+  lines.push(`- [Theming](${baseUrl}/docs/theming): Customization and design tokens`);
+  lines.push(`- [Form Controls](${baseUrl}/docs/form-controls): Form integration and validation`);
+  lines.push('');
+
+  //
+  // Components
+  //
+  lines.push('## Components');
+  lines.push('');
+
+  const sortedComponentsList = [...components].sort((a, b) => a.tagName.localeCompare(b.tagName));
+
+  for (const component of sortedComponentsList) {
+    const frontMatter = frontMatterCache.get(component.tagName);
+    const description = removeNewlines(frontMatter?.description || component.summary || '');
+    const componentSlug = component.tagName.replace(/^wa-/, '');
+    const title = frontMatter?.title || componentSlug;
+
+    lines.push(
+      `- [${title}](${baseUrl}/docs/components/${componentSlug}): ${description || 'No description available.'}`,
+    );
+  }
+  lines.push('');
+
+  //
+  // Optional
+  //
+  lines.push('## Optional');
+  lines.push('');
+  lines.push(
+    `The following is a quick reference describing every component's API. For comprehensive documentation, refer to the component documentation using the URLs provided above.`,
+  );
+  lines.push('');
+
+  // Sort components alphabetically by tag name for the API reference
+  const sortedComponents = [...components].sort((a, b) => a.tagName.localeCompare(b.tagName));
+
+  for (const component of sortedComponents) {
+    lines.push(...generateComponentApiSection(component, frontMatterCache, baseUrl));
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * A CEM plugin that generates an llms.txt file following the llmstxt.org specification.
+ */
+export function llmsTxtPlugin(options = {}) {
+  const {
+    outdir = 'dist-cdn',
+    docsDir = path.resolve(__dirname, '../docs'),
+    baseUrl = 'https://webawesome.com',
+  } = options;
+
+  return {
+    name: 'wa-llms-txt',
+    packageLinkPhase({ customElementsManifest }) {
+      const components = getAllComponents(customElementsManifest);
+      const packageData = customElementsManifest.package || {};
+      const frontMatterCache = loadAllFrontMatter(components, docsDir);
+
+      const llmsTxt = generateLlmsTxt({
+        components,
+        packageData,
+        frontMatterCache,
+        baseUrl,
+      });
+
+      // Write to the output directory
+      const outputPath = path.join(outdir, 'llms.txt');
+      fs.writeFileSync(outputPath, llmsTxt, 'utf-8');
+    },
+  };
+}
+
+export default llmsTxtPlugin;