css-comments-to-json

Generate styleguide JSON data from CSS comments.

English / 日本語

English

This package is inspired by Hologram and KSS. It parses documentation comments written close to your CSS components and turns them into structured styleguide data.

Unlike Hologram or many KSS-style tools, this package does not try to render a complete styleguide UI by itself. It focuses on generating JSON that can be consumed by Eleventy, Astro, VitePress, or any static site generator.

Why

Storybook is a powerful component workshop, and it is often the right tool for application components with many states, props, interactions, and visual tests.

But not every project needs that much machinery. For static sites, CSS-first component libraries, Eleventy/Nunjucks projects, corporate websites, landing pages, and CMS-oriented builds, a full component workshop can be more than the project needs.

css-comments-to-json is for projects where you want:

• CSS comments to be the source of truth for component usage.
• Class tables, descriptions, variants, and HTML examples to live near the CSS.
• Structured JSON that your existing static site generator can render.
• A lightweight alternative when Storybook is more than you need.
• Documentation that is easy for both humans and AI coding agents to read.

The basic flow is:

CSS comments
  -> styleguide JSON
  -> your static site generator

In short: this is a lightweight styleguide data generator for CSS-first projects, not a replacement for Storybook.

When To Use This

Use this when:

• You are building mostly static HTML/CSS sites.
• Your components are documented by class names and HTML examples.
• You already have an SSG such as Eleventy and want to render the styleguide there.
• You want Hologram/KSS-like CSS documentation without adopting a full UI workshop.
• You want AI tools to infer existing component usage from source-adjacent documentation.

Install

npm install -D css-comments-to-json

CLI

npx css-comments-to-json \
  --input "src/assets/css/**/*.css" \
  --output "src/_data" \
  --prefix styleguide

This writes files like:

src/_data/styleguidecomponent.json
src/_data/styleguidebase-component.json

CSS Comment Format

/*
* @sg-category Component
* @sg-name CTA
* @sg-description CTA component.
* @sg-table
* | Class | Description |
* |-------|-------------|
* | c-cta | CTA container |
* @sg-example
<div class="c-cta">
  CTA
</div>
*/

Supported tags:

• @sg-category
• @sg-name
• @sg-sub-name
• @sg-description
• @sg-table
• @sg-example
• @sg-markup
• @sg-variant

JavaScript API

import { generateStyleguideData } from 'css-comments-to-json';

await generateStyleguideData({
  input: 'src/assets/css/**/*.css',
  output: 'src/_data',
  prefix: 'styleguide',
});

For parsing a single CSS string:

import { parseStyleguideComments } from 'css-comments-to-json';

const data = parseStyleguideComments(css);

Options

Option	Default	Description
input	src/assets/css/**/*.css	CSS input glob
output	src/_data	Output directory
prefix	styleguide	Output filename prefix
cwd	process.cwd()	Working directory
dryRun	false	Return output files without writing
includeSource	false	Include source file and line

Config File

You can keep options in a JavaScript config file:

// css-comments-to-json.config.mjs
export default {
  input: 'src/assets/css/**/*.css',
  output: 'src/_data',
  prefix: 'styleguide',
  includeSource: true,
};

Run it with:

npx css-comments-to-json --config css-comments-to-json.config.mjs

CLI flags override config file values.

JSON Output

Each @sg-category becomes one JSON file. For example, Component with the default styleguide prefix becomes styleguidecomponent.json.

[
  {
    "name": "CTA",
    "id": "cta",
    "description": "CTA component.",
    "children": [],
    "tables": [
      "| Class | Description |\n|-------|-------------|\n| c-cta | CTA container |"
    ],
    "examples": [
      {
        "name": "default",
        "code": "<div class=\"c-cta\">\n  CTA\n</div>"
      }
    ]
  }
]

When includeSource is enabled, each component also includes source.file and source.line.

Warnings

The CLI prints warnings for incomplete styleguide comments, such as:

• Missing @sg-category
• Missing or empty @sg-name
• Empty @sg-example, @sg-markup, or @sg-table blocks
• @sg-sub-name, @sg-example, @sg-markup, or @sg-table before @sg-name

The JavaScript API returns the same warnings:

const result = await generateStyleguideData({
  input: 'src/assets/css/**/*.css',
});

console.log(result.warnings);

Eleventy

Use the CLI before Eleventy builds:

{
  "scripts": {
    "build:css-comments-json": "css-comments-to-json --input \"src/assets/css/**/*.css\" --output \"src/_data\" --prefix styleguide",
    "build": "npm run build:css-comments-json && eleventy"
  }
}

日本語

css-comments-to-json は、CSS 内の構造化コメントを読み取り、JSON に変換する小さな CLI/API です。

Hologram や KSS のような「CSS コメントを実装に近い場所へ置く」思想に影響を受けています。ただし、このパッケージ自体は完全なスタイルガイド UI を生成しません。CSS コメントから JSON を生成し、その JSON を Eleventy、Astro、VitePress など任意の静的サイトジェネレータで表示することに特化しています。

なぜ使うのか

Storybook は強力なコンポーネントワークショップです。状態、props、インタラクション、visual test が多いアプリケーションコンポーネントでは適した選択です。

一方で、すべてのプロジェクトに Storybook ほどの仕組みが必要とは限りません。静的サイト、CSS 中心のコンポーネント、Eleventy/Nunjucks、コーポレートサイト、LP、CMS 実装寄りの案件では、もう少し軽い仕組みの方が合うことがあります。

css-comments-to-json は、次のような場合に向いています。

• CSS コメントをコンポーネント利用方法の一次情報にしたい。
• class 一覧、説明、variant、HTML 例を CSS の近くに置きたい。
• 既存の静的サイトジェネレータでスタイルガイドを表示したい。
• Storybook までは不要だが、軽量なスタイルガイドデータは欲しい。
• 人間にも AI コーディングエージェントにも読みやすいコンポーネントドキュメントを作りたい。

基本の流れは次の通りです。

CSS コメント
  -> スタイルガイド用 JSON
  -> 任意の静的サイトジェネレータ

つまり、これは Storybook の代替ではなく、CSS-first なプロジェクト向けの軽量な JSON 生成ツールです。

向いているケース

向いているケース:

• 静的 HTML/CSS 中心のサイトを作っている。
• コンポーネントを class 名と HTML 例で管理している。
• Eleventy などの SSG が既にあり、その中でスタイルガイドを表示したい。
• Hologram/KSS 的な CSS ドキュメントは欲しいが、重いコンポーネントワークショップは不要。
• AI に既存コンポーネントの使い方を読み取らせたい。

インストール

npm install -D css-comments-to-json

CLI

npx css-comments-to-json \
  --input "src/assets/css/**/*.css" \
  --output "src/_data" \
  --prefix styleguide

次のような JSON を出力します。

src/_data/styleguidecomponent.json
src/_data/styleguidebase-component.json

CSS コメント形式

/*
* @sg-category Component
* @sg-name CTA
* @sg-description CTA コンポーネント。
* @sg-table
* | クラス名 | 説明 |
* |----------|------|
* | c-cta | CTA コンテナ |
* @sg-example
<div class="c-cta">
  CTA
</div>
*/

対応タグ:

• @sg-category
• @sg-name
• @sg-sub-name
• @sg-description
• @sg-table
• @sg-example
• @sg-markup
• @sg-variant

JavaScript API

import { generateStyleguideData } from 'css-comments-to-json';

await generateStyleguideData({
  input: 'src/assets/css/**/*.css',
  output: 'src/_data',
  prefix: 'styleguide',
});

CSS 文字列を直接パースする場合:

import { parseStyleguideComments } from 'css-comments-to-json';

const data = parseStyleguideComments(css);

オプション

Option	Default	Description
input	src/assets/css/**/*.css	CSS 入力 glob
output	src/_data	出力ディレクトリ
prefix	styleguide	出力ファイル名の prefix
cwd	process.cwd()	作業ディレクトリ
dryRun	false	ファイルを書き込まず、出力予定だけ返す
includeSource	false	出力に元ファイルと行番号を含める

設定ファイル

JavaScript の設定ファイルにオプションをまとめられます。

// css-comments-to-json.config.mjs
export default {
  input: 'src/assets/css/**/*.css',
  output: 'src/_data',
  prefix: 'styleguide',
  includeSource: true,
};

次のように実行します。

npx css-comments-to-json --config css-comments-to-json.config.mjs

CLI の指定は、設定ファイルの値を上書きします。

JSON 出力例

@sg-category ごとに 1 つの JSON ファイルを生成します。たとえば Component は、標準の styleguide prefix では styleguidecomponent.json になります。

[
  {
    "name": "CTA",
    "id": "cta",
    "description": "CTA component.",
    "children": [],
    "tables": [
      "| Class | Description |\n|-------|-------------|\n| c-cta | CTA container |"
    ],
    "examples": [
      {
        "name": "default",
        "code": "<div class=\"c-cta\">\n  CTA\n</div>"
      }
    ]
  }
]

includeSource を有効にすると、各コンポーネントに source.file と source.line も含まれます。

Warning

CLI は、不完全なスタイルガイドコメントに warning を出します。

• @sg-category がない
• @sg-name がない、または空
• @sg-example、@sg-markup、@sg-table の中身が空
• @sg-name より前に @sg-sub-name、@sg-example、@sg-markup、 @sg-table が出ている

JavaScript API でも同じ warning を取得できます。

const result = await generateStyleguideData({
  input: 'src/assets/css/**/*.css',
});

console.log(result.warnings);

Eleventy で使う

Eleventy のビルド前に CLI を実行します。

{
  "scripts": {
    "build:css-comments-json": "css-comments-to-json --input \"src/assets/css/**/*.css\" --output \"src/_data\" --prefix styleguide",
    "build": "npm run build:css-comments-json && eleventy"
  }
}