bullframe.css 6.0.0 → 6.2.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.2.0] - 2026-09-29
+
+### Added
+
+- AI agent skills: `bullframe-core`, `bullframe-landing-page`, `bullframe-forms`, `bullframe-docs-page`, `bullframe-convert`; `npx bullframe.css skills install` (Claude, Cursor, Codex).
+- Generated `api.json` (`.bf-*` classes, `--bf-*` tokens) in the package and at `/api.json`.
+- AI skills docs page; docs site 404 page.
+- `npm run test:e2e:sync-from-ci` to copy Playwright linux baselines from a CI run artifact.
+
+### Fixed
+
+- Non-existent classes in Grid, Cards, Spacing, and Text docs.
+- Wrong v6 token names in the migration guide.
+
+### Changed
+
+- npm publish is manual from the release tag; **Publish to npm** is `workflow_dispatch` only (no `release: published` trigger).
+
+### Security
+
+- Explicit `permissions: contents: read` on CI, Deploy docs, and Skills eval workflows.
+
+## [6.1.0] - 2026-09-14
+
+### Added
+
+- CSS variables `--bf-focus-ring-color`, `--bf-focus-ring-width`, `--bf-focus-ring-offset`.
+- `.bf-skip-link`, `.bf-focusable`, `.bf-scheme-*`, `.bf-target-size`, `.bf-accent-native`.
+- `@supports` for `text-wrap: balance` and `scrollbar-gutter: stable`.
+
+### Changed
+
+- README: install, CDN, examples; unversioned CDN (docs stay pinned + SRI).
+- README, hero, OG, and social preview images regenerated from one source (`npm run brand:images`).
+
+### Fixed
+
+- `caption` and `progress` in classless always-dark.
+- Accessibility markup in the kitchen sink and examples.
+- Docs site cache headers, so a new release reaches returning visitors.
+
+### Removed
+
+- Dead UA+ rules that never applied inside `@layer`.
+
 ## [6.0.0] - 2026-07-31 - BREAKING CHANGES
 
 ### Changed
@@ -489,5 +534,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial commit on 19 November 2012
 - Framework aimed to kickstart cross-browser responsive HTML/CSS development
 
-[Unreleased]: https://github.com/marcop135/bullframe.css/compare/v6.0.0...HEAD
+[Unreleased]: https://github.com/marcop135/bullframe.css/compare/v6.2.0...HEAD
+[6.2.0]: https://github.com/marcop135/bullframe.css/compare/v6.1.0...v6.2.0
+[6.1.0]: https://github.com/marcop135/bullframe.css/compare/v6.0.0...v6.1.0
 [6.0.0]: https://github.com/marcop135/bullframe.css/compare/v5.1.0...v6.0.0

package/README.md

@@ -1,38 +1,41 @@
 <div align="center">
 
-![Bullframe CSS](https://raw.githubusercontent.com/marcop135/bullframe.css/main/src/docs/github-readme/bf-readme-hero-light-16x9.png#gh-light-mode-only)
-![Bullframe CSS](https://raw.githubusercontent.com/marcop135/bullframe.css/main/src/docs/github-readme/bf-readme-hero-dark-16x9.png#gh-dark-mode-only)
+![Bullframe CSS](src/docs/github-readme/bf-readme-hero-light-16x9.png#gh-light-mode-only)
+![Bullframe CSS](src/docs/github-readme/bf-readme-hero-dark-16x9.png#gh-dark-mode-only)
 
 # Bullframe CSS
 
-Semantic by default. Any stack.<br>
-<em>Classless when you want it. System dark built in.</em>
+Semantic by default. Any stack.
 
 </div>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/bullframe.css"><img src="https://img.shields.io/npm/v/bullframe.css.svg?style=flat-square" alt="npm version"></a>
-  <a href="https://bullframecss.marcopontili.com/"><img src="https://img.shields.io/badge/docs-online-0056b3?style=flat-square" alt="Docs"></a>
-  <img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="Zero dependencies">
-  <img src="https://img.shields.io/badge/any%20stack-555555?style=flat-square" alt="Any stack">
+  <a href="https://github.com/marcop135/bullframe.css/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/marcop135/bullframe.css/ci.yml?branch=main&style=flat-square" alt="CI status"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/marcop135/bullframe.css.svg?style=flat-square" alt="MIT License"></a>
 </p>
 
 ---
 
-## Why use it
+One CSS file for plain HTML: type, forms, tables, buttons, and layout. No build step. No JavaScript.
 
-- **Semantic HTML first:** headings, forms, tables, and links are styled without a pile of classes
-- **Classless when you want it:** swap in `bullframe-classless.css` and keep markup as plain HTML
-- **Dark without a script:** always-dark builds, or system-default builds that follow `prefers-color-scheme`
-- **Accessible defaults:** focus-visible rings, reduced-motion respect, WCAG AA contrast on links and primary buttons
-- **Native CSS, any stack:** PostCSS builds, no Sass, no runtime JavaScript, solid cross-browser support
+Class-based or classless. Light, dark, or system. About 8 kB gzipped. Drop it on a landing, docs site, or help center.
 
-## When to use
+## Quick start
 
-Pages and forms, not complex app UIs: docs, blogs, landings, help centers, listings, micro-sites. One stylesheet for reset, type, forms, and layout. Class-based or classless. No Tailwind-style utility pipeline.
+1. Add the stylesheet (CDN, always the latest release):
 
-## Getting started
+<!-- sri:cdn:start -->
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css">
+```
+<!-- sri:cdn:end -->
+
+2. Write semantic HTML. Headings, forms, tables, and buttons are styled without classes.
+
+3. Swap the build when you need classless, dark, or system. See [Builds](#builds).
+
+Or install from npm:
 
 ```bash
 npm install bullframe.css
@@ -42,30 +45,101 @@ npm install bullframe.css
 import 'bullframe.css';
 ```
 
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css">
-```
+Default import: class-based, light. Other builds: `bullframe.css/classless`, `bullframe.css/dark`, and so on.
+
+[Docs](https://bullframecss.marcopontili.com/) · [Examples](https://bullframecss.marcopontili.com/examples)
 
-## Docs
+## Features
 
-[bullframecss.marcopontili.com](https://bullframecss.marcopontili.com/)
+- Plain HTML looks finished before you write a class
+- Classless when you want clean markup; classes when you need layout control
+- Light and dark out of the box, no theme script
+- One stylesheet, about 8 kB gzipped: type, forms, tables, buttons, layout
+- Restyle the page by changing a few colour tokens
+- Accessibility built in: clear focus, reduced motion, WCAG AA defaults
+- Works with any stack: landings, docs, help centers
+- npm or CDN; nothing to compile to use it
+- AI skills for coding agents: `npx bullframe.css skills install`
 
 ## Examples
 
-[Example templates](https://bullframecss.marcopontili.com/examples)
+Ready to copy: landings, blogs, forms, docs. Plain HTML, one stylesheet.
 
-## Kitchen sink
+<table>
+  <tr>
+    <td><a href="https://bullframecss.marcopontili.com/examples/typography/"><img src="src/docs/examples/screenshots/typography.png" alt="Typography" style="border: 1px solid #999; border-radius: 10px;" /></a></td>
+    <td><a href="https://bullframecss.marcopontili.com/examples/album/"><img src="src/docs/examples/screenshots/album.png" alt="Album" style="border: 1px solid #999; border-radius: 10px;" /></a></td>
+  </tr>
+  <tr>
+    <td><a href="https://bullframecss.marcopontili.com/examples/pricing/"><img src="src/docs/examples/screenshots/pricing.png" alt="Pricing" style="border: 1px solid #999; border-radius: 10px;" /></a></td>
+    <td><a href="https://bullframecss.marcopontili.com/examples/branded/"><img src="src/docs/examples/screenshots/branded.png" alt="Branded" style="border: 1px solid #999; border-radius: 10px;" /></a></td>
+  </tr>
+  <tr>
+    <td><a href="https://bullframecss.marcopontili.com/examples/blog/"><img src="src/docs/examples/screenshots/blog.png" alt="Blog" style="border: 1px solid #999; border-radius: 10px;" /></a></td>
+    <td><a href="https://bullframecss.marcopontili.com/examples/cover/"><img src="src/docs/examples/screenshots/cover.png" alt="Cover" style="border: 1px solid #999; border-radius: 10px;" /></a></td>
+  </tr>
+</table>
 
-[Every styled element in one page](https://bullframecss.marcopontili.com/kitchen-sink/)
+[Browse all examples →](https://bullframecss.marcopontili.com/examples)
 
-## Contributing
+## AI skills
 
-See [CONTRIBUTING.md](./.github/CONTRIBUTING.md). Bug reports and feature requests go through [issues](https://github.com/marcop135/bullframe.css/issues).
+Markdown skills for AI coding agents ship in the npm package. No server. No API key.
 
-## Author
+```bash
+npx bullframe.css skills install
+```
 
-[Marco Pontili](https://marcopontili.com)
+Writes skill files plus a managed `AGENTS.md` block, and the matching layout under `.claude`, `.cursor`, or `.agents` when those folders exist.
+
+Details: [AI skills](https://bullframecss.marcopontili.com/ai-skills).
+
+## Builds
+
+<details>
+<summary>See all 7 variants</summary>
+
+Seven files in `dist/css/`, each with a minified twin and a source map. Pick one; do not combine them, except utilities on top of another build.
+
+| Build                                    | npm subpath                      | Use when                             |
+| ---------------------------------------- | -------------------------------- | ------------------------------------ |
+| `bullframe.css`                          | `bullframe.css`                  | Class-based, light                   |
+| `bullframe-dark.css`                     | `bullframe.css/dark`             | Class-based, always dark             |
+| `bullframe-system-default.css`           | `bullframe.css/system`           | Class-based, `prefers-color-scheme`  |
+| `bullframe-classless.css`                | `bullframe.css/classless`        | Classless, light                     |
+| `bullframe-classless-dark.css`           | `bullframe.css/classless/dark`   | Classless, always dark               |
+| `bullframe-classless-system-default.css` | `bullframe.css/classless/system` | Classless, `prefers-color-scheme`    |
+| `bullframe-utilities.css`                | `bullframe.css/utilities`        | `.bf-*` helpers only, no base styles |
+
+**Classless** styles HTML tags only (no `.bf-*` classes). **Class-based** adds `.bf-*` grid, spacing, and helpers on top.
+
+</details>
+
+## Documentation
+
+| Topic | |
+| ----- | --- |
+| [Docs](https://bullframecss.marcopontili.com/) | Home |
+| [Getting started](https://bullframecss.marcopontili.com/getting-started) | Install and pick a build |
+| [Examples](https://bullframecss.marcopontili.com/examples) | Page templates |
+| [Kitchen sink](https://bullframecss.marcopontili.com/kitchen-sink/) | Every element in one place |
+| [Variables](https://bullframecss.marcopontili.com/variables) | `--bf-*` tokens |
+| [Components](https://bullframecss.marcopontili.com/components/) | Cards, modals, navigation, buttons |
+| [Theming](https://bullframecss.marcopontili.com/theming) | Colours and dark mode |
+| [API reference](https://bullframecss.marcopontili.com/api-reference) | Full token and class list |
+| [AI skills](https://bullframecss.marcopontili.com/ai-skills) | Skills for AI coding agents |
+| [Changelog](./CHANGELOG.md) | Release notes |
+
+## Contributing
+
+See [CONTRIBUTING.md](./.github/CONTRIBUTING.md).
+
+Bugs → [issues](https://github.com/marcop135/bullframe.css/issues).
 
 ## License
 
 [MIT](./LICENSE)
+
+## Author
+
+[Marco Pontili](https://marcopontili.com)

package/bin/bullframe.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/* Bullframe CSS command line.
+ *
+ * One job: copy the agent skills that ship in this package into the current project,
+ * in whatever layout the project's AI tooling reads. Zero dependencies, no network,
+ * no postinstall hook, and it never touches the framework's CSS.
+ *
+ *   npx bullframe.css skills list
+ *   npx bullframe.css skills install [--target claude,cursor,codex,agents,dir] [--dir <path>]
+ *   npx bullframe.css skills path
+ */
+import { cp, mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, '..');
+const skillsDir = path.join(packageRoot, 'dist', 'skills');
+
+const START = '<!-- bullframe:skills:start -->';
+const END = '<!-- bullframe:skills:end -->';
+const LOCAL_DIR = 'bullframe-skills';
+
+/** Tool targets that write into `$parent/skills/` with the same SKILL.md layout. */
+const TOOL_TARGETS = {
+  claude: { parent: '.claude', label: '.claude/skills' },
+  cursor: { parent: '.cursor', label: '.cursor/skills' },
+  codex: { parent: '.agents', label: '.agents/skills' },
+};
+
+const KNOWN_TARGETS = [...Object.keys(TOOL_TARGETS), 'agents', 'dir'];
+
+const USAGE = `bullframe.css - agent skills for the Bullframe CSS framework
+
+Usage
+  npx bullframe.css skills list
+  npx bullframe.css skills install [options]
+  npx bullframe.css skills path
+
+Install options
+  --target <list>   Comma separated: claude, cursor, codex, agents, dir.
+                    Default: agents, plus claude / cursor / codex when a
+                    .claude, .cursor, or .agents directory exists.
+  --dir <path>      Where the "dir" and "agents" targets copy the skills.
+                    Default: ./${LOCAL_DIR}
+  --dry-run         Print what would be written and exit without writing.
+  --force           Overwrite files that already differ.
+
+Other
+  --help, -h        This text
+  --version, -v     Package version
+`;
+
+function parseArgs(argv) {
+  const options = { targets: null, dir: null, dryRun: false, force: false };
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--target') options.targets = (argv[++i] ?? '').split(',').filter(Boolean);
+    else if (arg === '--dir') options.dir = argv[++i];
+    else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--version' || arg === '-v') options.version = true;
+    else if (arg.startsWith('-')) options.unknown = arg;
+    else positional.push(arg);
+  }
+
+  return { options, positional };
+}
+
+async function exists(target) {
+  try {
+    await access(target, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readIndex() {
+  try {
+    return JSON.parse(await readFile(path.join(skillsDir, 'index.json'), 'utf8'));
+  } catch {
+    fail(
+      `no skills found in ${skillsDir}.\nInstall the published package, or run "npm run skills:build" in a clone.`
+    );
+  }
+}
+
+function fail(message) {
+  console.error(`bullframe: ${message}`);
+  process.exit(1);
+}
+
+/** Replace the managed block in place, or append it. Never duplicates. */
+function mergeAgentsBlock(existing, body) {
+  const block = `${START}\n${body.trimEnd()}\n${END}\n`;
+  if (!existing) return block;
+
+  const start = existing.indexOf(START);
+  const end = existing.indexOf(END);
+  if (start !== -1 && end !== -1 && end > start) {
+    return existing.slice(0, start) + block.trimEnd() + existing.slice(end + END.length);
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${block}`;
+}
+
+async function writeFileIfNeeded(file, content, { dryRun, force }, written) {
+  const current = (await exists(file)) ? await readFile(file, 'utf8') : null;
+  if (current === content) {
+    written.push(`unchanged ${path.relative(process.cwd(), file)}`);
+    return;
+  }
+  if (current !== null && !force && !file.endsWith('AGENTS.md')) {
+    written.push(`skipped   ${path.relative(process.cwd(), file)} (exists, use --force)`);
+    return;
+  }
+  written.push(
+    `${current === null ? 'wrote    ' : 'updated  '} ${path.relative(process.cwd(), file)}`
+  );
+  if (dryRun) return;
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, content, 'utf8');
+}
+
+async function copyTree(from, to, { dryRun }, written, label) {
+  written.push(`${dryRun ? 'would copy' : 'copied   '} ${label}`);
+  if (dryRun) return;
+  await mkdir(path.dirname(to), { recursive: true });
+  await cp(from, to, { recursive: true, force: true });
+}
+
+/** Copy every skill plus `_shared` and `api.json` into `$parent/skills/`. */
+async function installToolLayout(index, parentDir, label, options, written) {
+  const root = path.join(parentDir, 'skills');
+  for (const skill of index.skills) {
+    await copyTree(
+      path.join(skillsDir, skill.name),
+      path.join(root, skill.name),
+      options,
+      written,
+      `${label}/${skill.name}/`
+    );
+  }
+  await copyTree(
+    path.join(skillsDir, '_shared'),
+    path.join(root, '_shared'),
+    options,
+    written,
+    `${label}/_shared/`
+  );
+  await writeFileIfNeeded(
+    path.join(root, '_shared', 'api.json'),
+    await readFile(path.join(skillsDir, 'api.json'), 'utf8'),
+    { ...options, force: true },
+    written
+  );
+}
+
+async function listSkills() {
+  const index = await readIndex();
+  console.log(`bullframe.css ${index.version} - ${index.skills.length} skills\n`);
+  for (const skill of index.skills) {
+    console.log(`  ${skill.name}`);
+    console.log(`    ${skill.description}`);
+    if (skill.requires?.length) console.log(`    requires: ${skill.requires.join(', ')}`);
+  }
+  console.log(`\nInstall with: npx bullframe.css skills install`);
+}
+
+async function installSkills(options) {
+  const index = await readIndex();
+  const cwd = process.cwd();
+  const localDir = path.resolve(cwd, options.dir ?? LOCAL_DIR);
+
+  let targets = options.targets;
+  if (!targets) {
+    targets = ['agents'];
+    for (const [name, { parent }] of Object.entries(TOOL_TARGETS)) {
+      if (await exists(path.join(cwd, parent))) targets.push(name);
+    }
+  }
+
+  const unknown = targets.filter((t) => !KNOWN_TARGETS.includes(t));
+  if (unknown.length) {
+    fail(`unknown target "${unknown[0]}". Use ${KNOWN_TARGETS.join(', ')}.`);
+  }
+
+  const written = [];
+
+  for (const name of Object.keys(TOOL_TARGETS)) {
+    if (!targets.includes(name)) continue;
+    const { parent, label } = TOOL_TARGETS[name];
+    await installToolLayout(index, path.join(cwd, parent), label, options, written);
+  }
+
+  if (targets.includes('agents') || targets.includes('dir')) {
+    for (const skill of index.skills) {
+      await copyTree(
+        path.join(skillsDir, skill.name),
+        path.join(localDir, skill.name),
+        options,
+        written,
+        `${path.relative(cwd, localDir)}/${skill.name}/`
+      );
+    }
+    for (const file of ['_shared', 'api.json', 'index.json']) {
+      await copyTree(
+        path.join(skillsDir, file),
+        path.join(localDir, file),
+        options,
+        written,
+        `${path.relative(cwd, localDir)}/${file}`
+      );
+    }
+  }
+
+  if (targets.includes('agents')) {
+    const agentsFile = path.join(cwd, 'AGENTS.md');
+    const body = await readFile(path.join(skillsDir, index.agentsBlock), 'utf8');
+    const existing = (await exists(agentsFile)) ? await readFile(agentsFile, 'utf8') : null;
+    await writeFileIfNeeded(
+      agentsFile,
+      mergeAgentsBlock(existing, body),
+      { ...options, force: true },
+      written
+    );
+  }
+
+  console.log(`bullframe.css ${index.version} - targets: ${targets.join(', ')}`);
+  for (const line of written) console.log(`  ${line}`);
+  if (options.dryRun) console.log('\nDry run: nothing was written.');
+}
+
+async function main() {
+  const { options, positional } = parseArgs(process.argv.slice(2));
+
+  if (options.version) {
+    const pkg = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+  if (options.help || positional.length === 0) {
+    console.log(USAGE);
+    return;
+  }
+  if (options.unknown) {
+    console.error(`bullframe: unknown option "${options.unknown}"\n`);
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  const [group, command] = positional;
+  if (group !== 'skills') {
+    console.error(`bullframe: unknown command "${group}"\n`);
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (command === 'list') return listSkills();
+  if (command === 'install') return installSkills(options);
+  if (command === 'path') {
+    console.log(skillsDir);
+    return;
+  }
+
+  console.error(`bullframe: unknown subcommand "${command ?? ''}"\n`);
+  console.log(USAGE);
+  process.exit(2);
+}
+
+main().catch((error) => fail(error.message));