@chassis-ui/docs 0.1.9 → 0.2.0

package/README.md

@@ -1,98 +1,105 @@
 # @chassis-ui/docs
 
-Shared Astro components and layouts for Chassis documentation sites.
+> Shared Astro layouts, components, and utilities for Chassis documentation sites.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-blue.svg)](https://www.npmjs.com/package/@chassis-ui/docs) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
 
 ## Overview
 
-This package provides reusable Astro components, layouts, and utilities specifically designed for building documentation websites within the Chassis UI ecosystem. It includes common documentation patterns, styling helpers, and content processing utilities.
+`@chassis-ui/docs` powers every documentation site in the Chassis ecosystem — the main `chassis-ui.com` website and the per-package docs for `chassis-css`, `chassis-tokens`, `chassis-icons`, `chassis-figma`, and `chassis-assets`. It ships pre-built layouts, navigation components, content-processing utilities, and SCSS helpers so each site stays consistent without duplicating code.
+
+> [!NOTE] This package is developed inside the [`chassis-website`](https://github.com/chassis-ui/website) monorepo at `packages/docs/` and published to npm. Source, issues, and pull requests live in that repository.
 
 ## Installation
 
-```bash
-npm install @chassis-ui/docs
+```sh
+pnpm add @chassis-ui/docs
 ```
 
-or with pnpm:
+or:
 
-```bash
-pnpm add @chassis-ui/docs
+```sh
+npm install @chassis-ui/docs
 ```
 
-## Peer Dependencies
+### Peer Dependencies
 
-This package requires the following peer dependencies:
+```json
+{
+  "astro": "^5.0.0"
+}
+```
 
-- `@chassis-ui/css`: Chassis CSS framework
-- `@chassis-ui/icons`: Chassis icon library
-- `@chassis-ui/tokens`: Chassis design tokens
-- `astro`: ^4.0.0 || ^5.0.0
+In practice, sites also install the rest of the Chassis stack — `@chassis-ui/css`, `@chassis-ui/tokens`, `@chassis-ui/icons` — to render the layouts and styles correctly.
 
 ## Usage
 
-### Importing Components
-
-```typescript
-// Import layouts
-import Layout from '@chassis-ui/docs/layouts/Layout.astro'
+```astro
+---
+import BaseLayout from '@chassis-ui/docs/layouts/BaseLayout.astro'
 import DocsLayout from '@chassis-ui/docs/layouts/DocsLayout.astro'
+import SingleLayout from '@chassis-ui/docs/layouts/SingleLayout.astro'
 
-// Import components
-import CodeBlock from '@chassis-ui/docs/components/CodeBlock.astro'
-import Callout from '@chassis-ui/docs/components/Callout.astro'
+import TableOfContents from '@chassis-ui/docs/components/TableOfContents.astro'
+import ThemeToggler from '@chassis-ui/docs/components/ThemeToggler.astro'
 
-// Import utilities
-import { generateTOC } from '@chassis-ui/docs'
-import { processImage } from '@chassis-ui/docs'
-```
+import { generateTOC, processImage } from '@chassis-ui/docs'
+---
 
-### Available Exports
+<SingleLayout title="About" description="…">
+  <slot />
+</SingleLayout>
+```
 
-This package exports:
+## Exports
 
-- **Layouts**: Pre-built Astro layouts for documentation pages
-- **Components**: Reusable documentation components (code blocks, callouts, navigation, etc.)
-- **Shortcodes**: MDX-compatible shortcode components
-- **Libraries**: Utility functions for content processing, TOC generation, and more
-- **Styles**: SCSS utilities and mixins
-- **Scripts**: Client-side JavaScript utilities
+| Subpath | Contents |
+| --- | --- |
+| `@chassis-ui/docs` | Library functions: `chassis`, `image`, `layout`, `rehype`, `toc`, `utils` |
+| `@chassis-ui/docs/layouts/*` | `BaseLayout`, `DocsLayout`, `RedirectLayout`, `SingleLayout` |
+| `@chassis-ui/docs/components/*` | `DocsSidebar`, `FeatureCard`, `NavLink`, `ResponsiveImage`, `TableOfContents`, `ThemeToggler` |
+| `@chassis-ui/docs/shortcodes/*` | MDX shortcode components |
+| `@chassis-ui/docs/libs/*` | Direct access to individual library modules |
+| `@chassis-ui/docs/js/*` | Client-side scripts |
+| `@chassis-ui/docs/scss/*` | SCSS utilities and partials |
 
-### Directory Structure
+### Source Layout
 
 ```
 src/
-├── components/     # Astro components
-│   └── shortcodes/ # MDX shortcode components
-├── layouts/        # Page layouts
-├── libs/           # Utility libraries
-├── js/             # Client-side scripts
-└── scss/           # Styling utilities
+├── components/      # Astro components (+ shortcodes/)
+├── layouts/         # Page layouts (+ head/, header/, footer/)
+├── libs/            # Utility libraries
+├── js/              # Client-side scripts
+└── scss/            # Styling utilities
 ```
 
-## Features
+## Chassis Ecosystem
 
-- **Content Processing**: Utilities for processing markdown and MDX content
-- **Table of Contents**: Automatic TOC generation from headings
-- **Image Optimization**: Helper functions for responsive images
-- **Syntax Highlighting**: Code block components with syntax highlighting
-- **Navigation**: Responsive documentation navigation components
-- **Search Integration**: Ready-to-use search components
-- **Accessibility**: WCAG-compliant components with proper ARIA attributes
+This package is part of the Chassis Design System's multi-repository architecture:
 
-## Development
+| Project | Description |
+| --- | --- |
+| [chassis-website](https://github.com/chassis-ui/website) | **Main website and home of `@chassis-ui/docs` (this package)** |
+| [chassis-css](https://github.com/chassis-ui/css) | CSS framework and component library |
+| [chassis-tokens](https://github.com/chassis-ui/tokens) | Design token generation and management |
+| [chassis-icons](https://github.com/chassis-ui/icons) | Icon library and build toolkit |
+| [chassis-assets](https://github.com/chassis-ui/assets) | Multi-platform asset management |
+| [chassis-figma](https://github.com/chassis-ui/figma) | Figma component documentation |
 
-This package is part of the Chassis UI monorepo. For development instructions, see the main repository documentation.
+All documentation sites in the ecosystem share this package for consistent layouts, components, and styling.
 
-## License
+## Contributing
 
-MIT © [Chassis UI](https://github.com/chassis-ui)
+Issues and pull requests are welcome — please file them in [`chassis-ui/website`](https://github.com/chassis-ui/website). For larger changes, open an issue first so we can agree on the approach before you write the code.
 
-## Contributing
+## License
 
-Contributions are welcome! Please read the contributing guidelines in the main repository.
+MIT © [Chassis UI](https://github.com/chassis-ui)
 
 ## Links
 
-- [Documentation](https://chassis-ui.com/docs)
-- [GitHub Repository](https://github.com/chassis-ui/website)
-- [Issue Tracker](https://github.com/chassis-ui/website/issues)
-- [Chassis UI Website](https://chassis-ui.com)
+- [chassis-ui.com](https://chassis-ui.com)
+- [npm package](https://www.npmjs.com/package/@chassis-ui/docs)
+- [Source repository](https://github.com/chassis-ui/website/tree/main/packages/docs)
+- [Issue tracker](https://github.com/chassis-ui/website/issues)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -44,20 +44,20 @@
     "astro": "^5.0.0"
   },
   "devDependencies": {
-    "@docsearch/css": "^3.9.0",
-    "@docsearch/js": "^3.9.0",
+    "@docsearch/css": "^4.6.2",
+    "@docsearch/js": "^4.6.2",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
-    "astro": "^5.13.9",
+    "astro": "^6.1.9",
     "github-slugger": "^2.0.0",
     "image-size": "^2.0.2",
-    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-to-string": "^4.0.0",
     "remark": "^15.0.1",
     "remark-html": "^16.0.1",
     "unified": "^11.0.5",
-    "unist-util-visit": "^5.0.0",
-    "zod": "^4.1.11"
+    "unist-util-visit": "^5.1.0",
+    "zod": "^4.3.6"
   }
 }

package/src/components/FeatureCard.astro

@@ -26,7 +26,7 @@ const hasContent = Astro.slots.has('default')
 // Build class strings
 const cardClasses = [
   'feature-item bg-even d-flex flex-column rounded-large',
-  'p-medium p-large-xlarge gap-medium gap-medium-xlarge',
+  'p-medium large:p-xlarge gap-medium medium:gap-xlarge',
   horizontal ? '' : 'h-100',
   classes
 ]
@@ -35,8 +35,8 @@ const cardClasses = [
 
 const headerClasses = [
   'feature-header d-flex',
-  'gap-medium gap-medium-xlarge',
-  horizontal ? 'flex-column flex-medium-row' : 'flex-column'
+  'gap-medium medium:gap-xlarge',
+  horizontal ? 'flex-column medium:flex-row' : 'flex-column'
 ].join(' ')
 ---
 
@@ -45,17 +45,17 @@ const headerClasses = [
     {
       icon && (
         <div class="feature-thumb">
-          <svg class="icon feature-icon icon-3xlarge icon-medium-4xlarge" aria-hidden="true">
+          <svg class="icon feature-icon icon-3xlarge medium:icon-4xlarge" aria-hidden="true">
             <use href={`#${icon}`} />
           </svg>
         </div>
       )
     }
     <div>
-      <h3 class="feature-title font-large font-medium-xlarge mb-3xsmall mb-medium-2xsmall">
+      <h3 class="feature-title font-large medium:font-xlarge mb-3xsmall medium:mb-2xsmall">
         <slot name="title" />
       </h3>
-      <p class="feature-body font-medium-large mb-0">
+      <p class="feature-body medium:font-large mb-0">
         <slot name="body" />
       </p>
     </div>

package/src/components/NavLink.astro

@@ -21,7 +21,7 @@ interface Props {
 const { active, class: className, ...props } = Astro.props
 ---
 
-<li class="nav-item col-6 col-large-auto">
+<li class="nav-item col-6 large:col-auto">
   <a
     aria-current={active ? true : undefined}
     class:list={['nav-link', className, { active }]}

package/src/components/ThemeToggler.astro

@@ -26,7 +26,7 @@ const { layout } = Astro.props
 >
   <svg class="icon theme-icon-active" aria-hidden="true"><use href="#circle-half-solid"></use></svg>
   <span
-    class=`${layout === 'examples' ? 'visually-hidden' : 'd-large-none ms-xsmall'}`
+    class=`${layout === 'examples' ? 'visually-hidden' : 'large:d-none ms-xsmall'}`
     id="cxd-theme-text">Toggle theme</span
   >
 </button>

package/src/components/shortcodes/Blockquote.astro

@@ -0,0 +1,31 @@
+---
+/**
+ * Blockquote
+ *
+ * Render a blockquote with optional attribution.
+ */
+
+interface Props {
+  /** Attribution text or HTML for the quote */
+  attr?: String
+}
+
+const { attr } = Astro.props
+---
+
+{
+  attr ? (
+    <figure>
+      <blockquote class="blockquote">
+        <slot />
+      </blockquote>
+      <figcaption class="attribution">
+        <Fragment set:html={attr} />
+      </figcaption>
+    </figure>
+  ) : (
+    <blockquote class="blockquote">
+      <slot />
+    </blockquote>
+  )
+}

package/src/components/shortcodes/CSSOnly.astro

@@ -0,0 +1,18 @@
+---
+/*
+ * Outputs badge to identify features that are only available in CSS and not in Figma
+ */
+
+interface Props {
+  tooltip?: string
+}
+
+const { tooltip = 'This feature is only available in CSS and not in Figma components.' } =
+  Astro.props
+---
+
+<span
+  class="badge large info smooth mb-medium rounded-medium"
+  data-cx-toggle="tooltip"
+  title={tooltip}>CSS Only</span
+>

package/src/components/shortcodes/DeprecatedIn.astro

@@ -0,0 +1,15 @@
+---
+/*
+ * Outputs badge to identify the version something was deprecated
+ */
+
+interface Props {
+  version: string
+}
+
+const { version } = Astro.props
+---
+
+<span class="badge large warning smooth mb-medium rounded-medium">
+  Deprecated in v{version}
+</span>

package/src/components/shortcodes/InFigma.astro

@@ -0,0 +1,21 @@
+---
+/*
+ * Outputs badge to identify features that are only available in CSS and not in Figma
+ */
+
+interface Props {
+  tooltip?: string
+  plural?: boolean
+}
+
+const { tooltip, plural } = Astro.props
+const tooltipText =
+  tooltip ??
+  `This variant${plural ? 's' : ''} exist${plural ? '' : 's'} in the Figma component library with bound design tokens.`
+---
+
+<span
+  class="badge large primary smooth mb-medium rounded-medium"
+  data-cx-toggle="tooltip"
+  title={tooltipText}>In Figma</span
+>

package/src/layouts/BaseLayout.astro

@@ -28,24 +28,34 @@ type Props = {
     // any override.
     main?: LayoutOverridesHTMLAttributes<'main'>
   }
-  // A string containing the robots meta tag content. If not set, the tag will not be rendered.
-  robots?: string
   // An override for the page title. If not defined, the title will either be the content of the `title` frontmatter
   // property when rendering a markdown page or default back to the one defined in the `config.yml` file.
   title?: string
+  // An override for the page description. If not defined, the description will either be the content of the
+  // `description` frontmatter property when rendering a markdown page or default back to the one defined in
+  // the `config.yml` file.
+  description?: string
+  // A string containing the robots meta tag content. If not set, the tag will not be rendered.
+  robots?: string
 } & MarkdownProps
 
 // The following props are automatically set by Astro (if defined) based on the markdown frontmatter when rendering a
 // markdown page. They can be accessed through the `Astro.props.frontmatter` object but note that they won't be set when
 // not rendering a markdown page.
-type MarkdownProps = { frontmatter?: Partial<CollectionEntry<'docs' | 'blog'>['data']> }
+type MarkdownProps = { frontmatter?: Partial<CollectionEntry<'docs'>['data']> }
+
+// This type is used to define the shape of the `extra_js` frontmatter property which allows adding extra JavaScript
+// files to a page by passing an array of objects containing the `src` and `async` properties.
+type ExtraJS = NonNullable<CollectionEntry<'docs'>['data']['extra_js']>[number]
 
 const { frontmatter, layout, overrides, robots } = Astro.props
 
 const title = Astro.props.title ?? frontmatter?.title ?? getConfig().title
-const description = frontmatter?.description
-  ? stripMarkdown(frontmatter.description)
-  : getConfig().description
+const description = Astro.props.description
+  ? stripMarkdown(Astro.props.description)
+  : frontmatter?.description
+    ? stripMarkdown(frontmatter.description)
+    : getConfig().description
 const thumbnail = frontmatter?.thumbnail
   ? `${frontmatter.thumbnail}`
   : 'static/images/social-image.png'
@@ -87,7 +97,9 @@ const mainProps = overrides?.main ?? {}
 
     {
       frontmatter?.extra_js &&
-        frontmatter.extra_js.map((js) => <script is:inline async={js.async} src={js.src} />)
+        frontmatter.extra_js.map((js: ExtraJS) => (
+          <script is:inline async={js.async} src={js.src} />
+        ))
     }
 
     {

package/src/layouts/DocsLayout.astro

@@ -26,6 +26,8 @@ interface Props {
 
 const { frontmatter, headings, id } = Astro.props
 
+type DocSection = NonNullable<typeof frontmatter.sections>[number]
+
 // Extract the directory/section from the ID (format: "directory/filename.mdx")
 const parentDirectory = id.includes('/') ? id.split('/')[0] : ''
 
@@ -40,10 +42,11 @@ if (frontmatter.toc) {
 ---
 
 <BaseLayout {...Astro.props} layout="docs" overrides={{ body: bodyProps }}>
-  <div slot="main" class="container-fluid cxd-gutter cxd-layout">
+  <div slot="main" class="container fluid cxd-gutter cxd-layout">
     <aside class="cxd-sidebar">
       <div
-        class="offcanvas-large offcanvas-start"
+        class="large:offcanvas offcanvas-start"
+        role="dialog"
         tabindex="-1"
         id="cxdSidebar"
         aria-labelledby="cxdSidebarOffcanvasLabel"
@@ -70,9 +73,9 @@ if (frontmatter.toc) {
       <div class="cxd-intro">
         <slot name="intro">
           <div
-            class="d-medium-flex flex-medium-row-reverse justify-content-between align-items-start"
+            class="medium:d-flex medium:flex-row-reverse justify-content-between align-items-start"
           >
-            <div class="mb-medium mb-medium-0 d-flex text-nowrap">
+            <div class="mb-medium medium:mb-0 d-flex text-nowrap">
               {
                 // This is needed because we want to show the badge if show_badge isn't present or is set to false
                 frontmatter.added &&
@@ -110,7 +113,7 @@ if (frontmatter.toc) {
         frontmatter.toc && headings && (
           <div class="cxd-toc">
             <button
-              class="button default mb-large text-decoration-none cxd-toc-toggle d-medium-none"
+              class="button default mb-large text-decoration-none cxd-toc-toggle medium:d-none"
               type="button"
               data-cx-toggle="collapse"
               data-cx-target="#tocContents"
@@ -122,8 +125,8 @@ if (frontmatter.toc) {
                 <use xlink:href="#chevron-sort-solid" />
               </svg>
             </button>
-            <strong class="d-none d-medium-block h6 my-xsmall">On this page</strong>
-            <hr class="d-none d-medium-block my-xsmall" />
+            <strong class="d-none medium:d-block h6 my-xsmall">On this page</strong>
+            <hr class="d-none medium:d-block my-xsmall" />
             <div class="collapse cxd-toc-collapse" id="tocContents">
               <nav id="TableOfContents">
                 <slot name="toc">
@@ -139,8 +142,8 @@ if (frontmatter.toc) {
         {
           frontmatter.sections && (
             <div class="row g-xlarge">
-              {frontmatter.sections.map((section) => (
-                <div class="col-medium-6">
+              {frontmatter.sections.map((section: DocSection) => (
+                <div class="medium:col-6">
                   <a
                     class="d-block text-decoration-none"
                     href={getChassisDocsPath(

package/src/layouts/SingleLayout.astro

@@ -6,36 +6,33 @@
  */
 
 import BaseLayout from './BaseLayout.astro'
+import type { LayoutOverridesHTMLAttributes } from '../libs/layout'
 
 interface Props {
-  /** Page description */
-  description: string
   /** Page title */
   title: string
+  /** Page description */
+  description: string
 }
 
 const { description, title } = Astro.props
+
+const mainProps: LayoutOverridesHTMLAttributes<'main'> = {}
+mainProps['class'] = 'min-vh-100'
 ---
 
-<BaseLayout {...Astro.props} layout="single">
-  <Fragment slot="main">
-    <header class="py-xlarge border-bottom">
-      <div class="container-2xlarge cxd-gutter pt-medium-1 pb-medium-4">
-        <div class="row">
-          <div class="col-xlarge-8">
-            <h1 class="cxd-title mt-0">{title}</h1>
-            <p class="cxd-subtitle">{description}</p>
-            <slot name="header-content" />
-          </div>
+<BaseLayout {...Astro.props} layout="single" overrides={{ main: mainProps }}>
+  <header class="py-xlarge medium:py-3xlarge border-bottom border-subtle">
+    <div class="container 2xlarge">
+      <div class="row">
+        <div class="col large:col-10 2xlarge:col-8">
+          <h1 class="mt-0">{title}</h1>
+          <p class="font-lead">{description}</p>
+          <slot name="header-content" />
         </div>
       </div>
-    </header>
+    </div>
+  </header>
 
-    <main class="cxd-content order-1 py-xlarge" id="content">
-      <div class="container-2xlarge cxd-gutter">
-        <slot />
-        <slot name="main-content" />
-      </div>
-    </main>
-  </Fragment>
+  <slot />
 </BaseLayout>

package/src/layouts/footer/Footer.astro

@@ -7,9 +7,9 @@
 ---
 
 <footer class="cxd-footer py-6xlarge">
-  <div class="container-2xlarge fg-subtle">
+  <div class="container 2xlarge fg-subtle">
     <div class="row">
-      <div class="col-medium-10 col-large-5 mb-medium">
+      <div class="medium:col-10 large:col-5 mb-medium">
         <a
           class="d-inline-flex align-items-center mb-xsmall text-body-emphasis text-decoration-none"
           href="/"
@@ -22,8 +22,8 @@
           and distribution of the software.
         </p>
       </div>
-      <div class="col-small-4 col-large-2 offset-large-1 mb-medium">
-        <h5>Docs</h5>
+      <div class="small:col-4 large:col-2 large:offset-1 mb-medium">
+        <p class="h6 mb-xsmall">Docs</p>
         <ul class="nav">
           <li><a href="/tokens">Design Tokens</a></li>
           <li><a href="/assets">Asset Distributor</a></li>
@@ -32,8 +32,8 @@
           <li><a href="/icons">Icon Generator</a></li>
         </ul>
       </div>
-      <div class="col-small-4 col-large-2 mb-medium">
-        <h5>Github</h5>
+      <div class="small:col-4 large:col-2 mb-medium">
+        <p class="h6 mb-xsmall">Github</p>
         <ul class="nav">
           <li><a href="https://github.com/chassis-ui/tokens">Chassis Tokens</a></li>
           <li><a href="https://github.com/chassis-ui/assets">Chassis Assets</a></li>
@@ -42,13 +42,14 @@
           <li><a href="https://github.com/chassis-ui/icons">Chassis Icons</a></li>
         </ul>
       </div>
-      <div class="col-small-4 col-large-2 mb-medium">
-        <h5>About</h5>
+      <div class="small:col-4 large:col-2 mb-medium">
+        <p class="h6 mb-xsmall">Project</p>
         <ul class="nav">
+          <li><a href="/about">About</a></li>
           <li><a href="/blog">Blog</a></li>
-          <li><a href="https://x.com/chassis_ui">Chassis UI</a></li>
+          <li><a href="/examples">Examples</a></li>
           <li><a href="https://github.com/chassis-ui">Contribute</a></li>
-          <li><a href="https://github.com/ozgurgunes">Developer</a></li>
+          <li><a href="https://x.com/chassis_ui">@chassis_ui on X</a></li>
         </ul>
       </div>
     </div>

package/src/layouts/footer/Scripts.astro

@@ -17,11 +17,13 @@ const { layout } = Astro.props
 ---
 
 <script is:inline {...getChassisJsProps()}></script>
-
 <script src="../../js/search.js"></script>
-
+<script>
+  const tooltipTriggerList = document.querySelectorAll('[data-cx-toggle="tooltip"]')
+  const tooltipList = [...tooltipTriggerList].map(
+    (tooltipTriggerEl) => new chassis.Tooltip(tooltipTriggerEl)
+  )
+</script>
 {layout === 'docs' && <script src="../../js/sidebar.js" />}
-
 <script src="../../js/icon-loader.js"></script>
-
 <slot name="scripts" />