AGENTS.md

Guidance for AI coding agents working in this repository. Tool-agnostic; CLAUDE.md points here.

Bootstrap v6.0.0-alpha1 — CSS/JS framework. Sass source in scss/, TypeScript source in js/src/, docs site in site/ (Astro 5 + MDX).

Quick commands

  • npm start — dev server (watch + Astro on port 9001)
  • npm run dist — full CSS + JS build
  • npm run css — compile, prefix, minify CSS
  • npm run js — compile + minify JS
  • npm run css-lint / npm run js-lint — lint
  • npm run docs-build — build docs site
  • npm test — full test suite (lint + dist + tests + docs)

Writing style

Use ASD-STE100 Simplified Technical English for all prose: replies to the user, docs, code comments, commit messages, and PR text.

  • Write short sentences. Use approximately 20 words or fewer.
  • Give one instruction per sentence.
  • Use the active voice. Name the actor.
  • Use simple verbs. Do not use a complex verb when a simple one works.
  • Use one term for one thing. Keep terms the same across the project.
  • Keep paragraphs short. Cover one topic per paragraph.

Reply length

Be extremely brief. Report the result, not the journey.

  • Target 75 words or fewer. Hard cap 150 words, and only for a genuinely multi-part answer.
  • Answer in the first sentence. Then stop.
  • Give one supporting fact per claim, at most. Cut the rest.
  • Do not narrate your process, tool calls, or verification steps. Report a check only when it failed or changed the outcome.
  • Do not restate the work you just did. The user reads the diff, the commit, and the PR.
  • State a finding once. Never repeat it in a summary or closing line.
  • No headings. No tables. Use a list of 5 items or fewer only when the answer is a real list.
  • Cut praise, apologies, hedging, and filler such as “great question” or “worth noting”.
  • Do not explain what you did not do, or list caveats the user did not ask about.
  • Do not offer next steps unless the user asks or the work is blocked.
  • Expand only when the user asks for detail, or asks you to teach.

Teaching

Act as a teacher for JavaScript, TypeScript, React, and all JavaScript-family topics.

  • When the work hits a new problem, concept, or language feature, stop and explain it.
  • Keep each explanation short and plain. Define jargon on first use.
  • Use a small code example when it makes the idea clear.
  • Assume strong HTML/CSS knowledge. Do not assume deep JS internals knowledge.

SCSS conventions

  • Variable naming: $component-state-property-size (e.g., $nav-link-disabled-color)
  • Module system: @use / @forward only — never @import
  • Token system: component tokens are SCSS maps of CSS custom properties, merged via defaults(), output via @include tokens($map) on the component root selector
  • Disallowed: raw border-radius / transition properties (use mixins), lighten() / darken(), border: none / outline: none
  • Order: @use → @forward → $variables → --custom-properties → declarations → rules
  • Variables use !default (except locals)
  • CSS layers: colors, theme, config, root, reboot, layout, content, forms, components, custom, helpers, utilities
  • Logical properties: prefer padding-inline-start over padding-left, etc.
  • Modern CSS: color-mix(), light-dark(), range media queries (@media (width >= 1024px))
  • Doc markers: // scss-docs-start name / // scss-docs-end name for docs extraction

JavaScript/TypeScript conventions

  • Source is TypeScript (js/src/**/*.ts, entry js/src/index.ts); ESM-only, no semicolons, 2-space indent
  • Imports use .js extensions (standard TS ESM style); Rolldown resolves them to .ts via resolve.extensionAlias, Vitest via the tsResolve plugin in js/tests/vitest.config.mts
  • Dist builds use Rolldown (build/rolldown.config.mjs, build/build-plugins.mjs) with built-in TS transforms; build/browser-targets.mjs derives the browser floors from .browserslistrc at build time, so there is nothing to keep in sync. Rollup and Babel are gone from the repo — Vitest transforms the specs itself
  • Strict tsconfig with verbatimModuleSyntax + erasableSyntaxOnly; tsc only type-checks and emits .d.ts (npm run js-typecheck, npm run js-emit-types)
  • Components extend BaseComponent (which extends Config); per-component config type XxxConfig typed off Default, refined on the class via protected declare _config: XxxConfig
  • Instance fields use declare (no runtime emit); constructor element param stays optional to keep typeof Component assignable to typeof BaseComponent
  • Every _-prefixed instance member is protected (never private, so subclasses keep access); public API methods and statics stay public. This keeps the internals out of the published .d.ts surface
  • Constants: NAME, DATA_KEY, EVENT_KEY, VERSION
  • DOM utilities via dom/event-handler.ts, dom/selector-engine.ts, dom/manipulator.ts
  • Floating UI for positioning (dropdown, tooltip, popover)
  • Tests: Vitest browser mode (real Chromium via Playwright), config in js/tests/vitest.config.mts, specs in js/tests/unit/*.spec.js (plain JS, bundled against the TS sources). js/tests/vitest-setup.js maps the Jasmine API the specs are written against onto Vitest — note spyOn stubs by default, unlike vi.spyOn. Async specs return a promise; Vitest 4 dropped done. Coverage is Istanbul over all of js/src, thresholds 90/88/90/90
  • Type-level API tests in js/tests/types/ — api.ts checks the source (npm run js-typecheck), consumer.ts checks the shipped js/dist/*.d.ts through the package exports map (npm run js-typecheck-dist, after the build). Keep the two in sync

Docs conventions

  • Astro 5 + MDX in site/src/content/docs/
  • Frontmatter schema: title (required), description (required), toc, aliases, added, mdn, reference, etc.
  • Shortcodes: Example, Callout, Code, Details
  • Internal links: [[docsref:/path/]]
  • JS component “Dependencies” tables are auto-generated — add a ### Dependencies heading with <JsDependencies component="<js-src-basename>" /> (before ### Options) on any doc for a js/src/*.ts component. The table is derived at build time by walking the component's import graph in site/src/libs/js-dependencies.ts; never hand-write the file list. When a new source file or third-party package enters the graph, add its human-readable label to FILE_DESCRIPTIONS / PACKAGE_DESCRIPTIONS in that lib (the build throws if a label is missing).

Formatting

  • 2 spaces, UTF-8, LF line endings, trim trailing whitespace, final newline
  • Preserve smart punctuation (curly apostrophes U+2019, curly quotes) — never replace with ASCII equivalents
  • Use StrReplace for targeted edits; avoid full-file rewrites on MDX files to protect typography

Workflow

  • Validate after changes: npm run css-lint, npm run js-lint, npm run dist, npm run docs-build
  • Keep config files in sync: config.yml, site/src/libs/config.ts (Zod schema), build/rolldown.config.mjs, build/generate-sri.mjs, package.json
  • For rebases/conflicts: favor base branch structure, layer feature changes on top

Commits & PRs

  • Commit messages: direct, succinct prose explaining why the change was made.
  • PR descriptions: direct bulleted lists, minimal fluff — one bullet per notable change.
  • Reference related issues/PRs explicitly with Fixes #{issue}, Closes #{issue}, or Supersedes #{pr}.
  • No “Test plan” section and no extra headings — just the bullets and the references.

Do not edit

Built output in dist/, _site/, js/dist/ — these are generated.