inclusion-md 0.1.0

package/bin/inclusion-md.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const { init } = require("../lib/init");
+
+const HELP = `inclusion-md - scaffold an INCLUSION.md for your repository.
+
+Usage:
+  npx inclusion-md init [options]
+  npx inclusion-md --help
+
+Commands:
+  init                 Interactively generate an INCLUSION.md.
+
+Options:
+  -o, --out <path>     Output path (default: ./INCLUSION.md).
+      --variant <name> Start from a variant template:
+                       generic (default) | frontend-app | design-system | backend-api
+      --force          Overwrite an existing INCLUSION.md without prompting.
+      --yes            Accept defaults for any unanswered prompts.
+      --no-color       Disable ANSI color output.
+  -h, --help           Show this help.
+  -v, --version        Show CLI version.
+
+Examples:
+  npx inclusion-md init
+  npx inclusion-md init --variant design-system
+  npx inclusion-md init --out docs/INCLUSION.md --force
+
+Read more: https://github.com/BranonConor/inclusion.md
+`;
+
+function parseArgs(argv) {
+  const args = {
+    command: null,
+    out: null,
+    variant: null,
+    force: false,
+    yes: false,
+    color: true,
+    help: false,
+    version: false,
+  };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "-h" || a === "--help") args.help = true;
+    else if (a === "-v" || a === "--version") args.version = true;
+    else if (a === "--force") args.force = true;
+    else if (a === "--yes" || a === "-y") args.yes = true;
+    else if (a === "--no-color") args.color = false;
+    else if (a === "-o" || a === "--out") args.out = rest[++i];
+    else if (a === "--variant") args.variant = rest[++i];
+    else if (!a.startsWith("-") && !args.command) args.command = a;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (args.version) {
+    const pkg = require("../package.json");
+    console.log(pkg.version);
+    return;
+  }
+  if (!args.command) args.command = "init";
+
+  if (args.command !== "init") {
+    console.error(`Unknown command: ${args.command}`);
+    process.stdout.write("\n" + HELP);
+    process.exit(2);
+  }
+
+  try {
+    await init(args);
+  } catch (err) {
+    if (err && err.code === "USER_CANCELLED") {
+      console.error("\nCancelled. No file was written.");
+      process.exit(130);
+    }
+    console.error("\nError:", err && err.message ? err.message : err);
+    process.exit(1);
+  }
+}
+
+main();

package/examples/backend-api/INCLUSION.md

@@ -0,0 +1,118 @@
+# INCLUSION.md - Backend API / SDK (example)
+
+> Example adaptation for a backend API or SDK.
+
+Backend systems are not exempt from inclusion considerations. Schema choices,
+error messages, rate limits, language defaults, and data models ripple
+outward into every UI and integration that consumes them.
+
+This file extends the base [`INCLUSION.md`](../../INCLUSION.md) template.
+
+---
+
+## 1. Project Context
+
+- **Product:** [API or SDK description.]
+- **Primary consumers:** Internal teams and/or external developers.
+- **End-user impact:** This API mediates [user data, authentication,
+  payments, messaging, etc.] for downstream products. Exclusionary defaults
+  here become exclusionary defaults everywhere.
+- **Distribution context:** Used in [N] downstream products across [regions
+  / locales / device classes].
+- **Stakes:** Schema and validation choices made here are extremely difficult
+  to roll back once published.
+
+---
+
+## 2. Schema & Data Model Guidance
+
+Generated and hand-authored schemas in this repo should:
+
+- **Names:** A single `full_name` string field (Unicode, up to 255
+  characters, no validation against "first/last" splits). Optionally a
+  separate `display_name` or `preferred_name`. If legal name is required
+  separately for compliance, name the field `legal_name` and document why.
+  See Patrick McKenzie, _Falsehoods Programmers Believe About Names_:
+  <https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/>.
+- **Email:** Validate per RFC 5321 + 5322. Do not enforce
+  ASCII-only or single-`@` heuristics.
+- **Phone:** Store E.164. Accept any digits and the international format on
+  input.
+- **Addresses:** Support multi-line, international addresses. Do not require
+  US states or 5-digit ZIPs.
+- **Gender / pronouns:** Optional, free-text, plus an enumerated suggestion
+  list. Never required. Never used for access control.
+- **Date of birth:** Stored as ISO 8601 date, no assumed minimum or maximum
+  year. Do not collect unless legally required.
+- **Time:** Always store UTC. Always expose timezone separately. Never
+  assume the consumer's locale.
+- **Language:** Every endpoint accepts `Accept-Language`. Every response
+  includes a `Content-Language`. Default to the user's stated preference,
+  not the server's locale.
+- **Currency:** Store amounts as integer minor units (cents) + ISO 4217
+  currency code. Never assume USD.
+- **Units:** Expose units explicitly. Never assume imperial vs. metric.
+
+---
+
+## 3. Error Messages & API Surface
+
+API error messages are user-facing more often than designers admit.
+
+- Error messages must be plain language and translatable. Provide a stable
+  `error_code` separate from the human-readable `message`.
+- Never leak PII, secrets, or stack traces in error responses.
+- Provide a `next_steps` or `documentation_url` field where helpful.
+- Do not blame the caller for ambiguous input. "We couldn't find that
+  account" is more usable than "INVALID_INPUT."
+- Validation errors return per-field detail so downstream UIs can render
+  accessible inline form errors.
+
+---
+
+## 4. Rate Limits, Quotas, and Accessibility
+
+- Rate limits should not penalize assistive-technology-driven traffic
+  patterns. Screen reader users often re-request pages, refocus, and
+  re-trigger flows.
+- Provide a `Retry-After` header and a documented exponential backoff
+  strategy. Do not silently drop requests.
+- For paginated endpoints, expose total counts and cursors. Infinite scroll
+  without an end is hostile to screen reader and keyboard users.
+- Do not use CAPTCHA as a primary anti-abuse strategy. Where CAPTCHA is
+  unavoidable, support accessible alternatives.
+
+---
+
+## 5. Authentication & Identity
+
+- Support more than one factor of authentication, and more than one type of
+  second factor (TOTP, hardware key, SMS as last resort, email).
+- Do not require SMS as the only second factor. SMS excludes users without
+  reliable cell service, users abroad, and users with shared phones.
+- Support account recovery flows that do not depend on a single device or
+  carrier.
+- Never lock users out of their own data because they have changed name,
+  gender marker, address, or contact info.
+
+---
+
+## 6. Logging, Analytics, and Privacy
+
+- Log levels: never log PII at INFO or above. Audit before adding fields.
+- Do not log message bodies, names, addresses, or identifiers in plaintext
+  to shared aggregators.
+- Telemetry: opt-in for end-user-identifying telemetry. Opt-out is not
+  consent.
+- Anonymization is hard. Aggregate where possible. Hash with care.
+
+---
+
+## 7. SDK Documentation
+
+- Code examples in SDK docs use realistic, internationally varied sample
+  data - not "John Doe, 123 Main St, USA."
+- Document defaults explicitly so consumers can override them per locale.
+- Document accessibility implications of API choices (e.g. "this endpoint
+  returns infinite-scroll cursors; consumers must provide an end-of-results
+  cue for assistive tech").

package/examples/design-system/INCLUSION.md

@@ -0,0 +1,92 @@
+# INCLUSION.md - Design System (example)
+
+> Example adaptation for a component library or design system.
+
+This file extends the base [`INCLUSION.md`](../../INCLUSION.md) template with
+guidance specific to a design system whose components are reused across many
+products.
+
+Design systems sit upstream of every product surface they touch. Their
+inclusion defaults become every downstream team's path of least resistance.
+That makes their `INCLUSION.md` unusually high-leverage.
+
+---
+
+## 1. Project Context
+
+- **Product:** [Design system name.] Provides foundational components,
+  tokens, and patterns to [N] downstream product teams.
+- **Primary users:** Product engineers and designers consuming components.
+- **End users:** Every user of every product that consumes this system. We
+  do not get to assume who they are.
+- **Known underserved users:** [Document known gaps. Examples: "Right-to-left
+  layouts are partial. Switch-control support is unverified. Component-level
+  text scaling above 200% breaks several layouts."]
+- **Distribution context:** Used in [N] products spanning [web / iOS /
+  Android / desktop]. Localized to [N] languages including RTL scripts.
+- **Stakes:** A regression here is a regression in every downstream product.
+
+---
+
+## 2. Component Authoring Requirements
+
+Generated or hand-authored components in this repo must:
+
+- Have a documented accessible name, role, and state model.
+- Be keyboard operable per the ARIA Authoring Practices Guide pattern for
+  that component type. Cite the pattern in the component's README.
+- Manage focus correctly: focus trap in modals, focus restoration on close,
+  visible focus indicator on every interactive element meeting WCAG 2.4.11.
+- Pass automated checks (axe, Pa11y, or equivalent) at the component level.
+- Have at least one screen-reader test plan documented in the component's
+  README.
+- Support `prefers-reduced-motion` for any animation.
+- Support `forced-colors: active` and high-contrast modes.
+- Use design tokens for color, spacing, type, and motion - never hardcoded
+  values - so themes, contrast modes, and density preferences can apply.
+- Support RTL layouts. Use logical CSS properties (`margin-inline-start`,
+  `padding-block-end`, etc.) instead of physical ones (`margin-left`).
+- Support variable text length: components must not break when localized
+  strings are 30-40% longer than English defaults.
+- Not assume a single language direction, locale, or numeric system.
+
+---
+
+## 3. Token Design
+
+- Color tokens are paired with intent (text, surface, border, focus, danger,
+  success) and contrast role - not raw hex values exposed downstream.
+- Every text-on-surface token pair has documented contrast ratios meeting
+  WCAG 2.2 AA at minimum.
+- Provide a high-contrast token theme.
+- Provide a token theme for `prefers-reduced-transparency`.
+- Motion tokens have a `none` variant that resolves when
+  `prefers-reduced-motion: reduce` is set.
+- Density tokens (compact, default, spacious) preserve a 24x24 minimum touch
+  target even at the most compact setting.
+
+---
+
+## 4. Documentation & Examples
+
+- Every component README includes: accessible name model, keyboard
+  interactions, screen-reader behavior, RTL behavior, localization notes,
+  known limitations.
+- Examples in documentation use realistic, diverse user names, addresses,
+  and content. Avoid placeholder names like "John Doe" or "Jane Smith" by
+  default. Use a curated set of realistic, internationally varied placeholder
+  data.
+- Example imagery includes a representative range of skin tones, body types,
+  ages, abilities, and contexts. No tokenized "diversity stock photo" set.
+- Do not document accessibility features as "bonus." They are baseline.
+
+---
+
+## 5. Deprecation & Migration
+
+- When deprecating a component or token, provide an automated migration path
+  (codemod) where feasible, and a documented manual path otherwise.
+- Never silently change accessibility behavior. Breaking changes to focus,
+  ARIA, or keyboard interaction must be flagged in release notes.
+- Provide at least one major version of overlap before removing a deprecated
+  inclusive feature.

package/examples/frontend-app/INCLUSION.md

@@ -0,0 +1,100 @@
+# INCLUSION.md - Frontend Web App (example)
+
+> Example adaptation for a consumer-facing frontend web application.
+> Replace bracketed placeholders with values for your project.
+
+This file extends the base [`INCLUSION.md`](../../INCLUSION.md) template with
+guidance specific to a public, consumer-facing web app.
+
+---
+
+## 1. Project Context
+
+- **Product:** [Short description of the web app and what users come here to do.]
+- **Primary users:** [e.g. "US-based adults managing personal finances."]
+- **Known underserved users:** [e.g. "Screen reader users on the dashboard;
+  Spanish-language users in onboarding; users on Android Go devices."]
+- **Distribution context:** Web. Modern evergreen browsers + last 2 versions
+  of Safari/Firefox. Mobile web is [N]% of traffic. Top non-English language
+  in analytics is [language]. Assistive tech in our analytics includes
+  [VoiceOver, NVDA, JAWS, TalkBack, Dragon, Switch Control].
+- **Stakes:** [e.g. "Users who cannot complete onboarding lose access to
+  [service]. This is not a low-stakes flow."]
+
+---
+
+## 2. Frontend-Specific Engineering Guidance
+
+In addition to the base `INCLUSION.md` Section 8, generated frontend code in
+this repo should:
+
+- Use semantic HTML elements (`<button>`, `<a>`, `<nav>`, `<main>`,
+  `<section>`, `<label>`, `<input>`, `<dialog>` where supported). Never
+  `div` + `onClick` for interactive controls.
+- Manage focus on route changes, modal open/close, and async state
+  transitions.
+- Pair every icon-only button with an `aria-label` or visually hidden text.
+- Use `aria-live` regions for important async updates (form errors, toast
+  notifications, search results) and verify them with a screen reader before
+  merging.
+- Never rely on hover, color, or position alone to convey state.
+- Support `prefers-reduced-motion` for all transitions and animations.
+- Default to system color scheme. Provide a manual override.
+- Lazy-load images and below-the-fold media. Always provide meaningful `alt`
+  text. Decorative imagery uses `alt=""`.
+- Render text content server-side wherever possible to support assistive tech
+  and slow networks.
+- Test interactive components with keyboard alone before merging.
+
+---
+
+## 3. Copy & Microcopy
+
+- Default reading level: US grade 7. Consent, onboarding, and error states:
+  grade 6.
+- Error messages should: (1) name the problem in plain language, (2) tell the
+  user what to do next, (3) preserve their input. Never blame the user.
+- Empty states should explain what the user can do, not just that there is
+  nothing here.
+- Avoid jokes, idioms, and US-cultural references in core flows. They do not
+  localize.
+
+---
+
+## 4. Forms
+
+Forms are where most exclusion happens.
+
+- Every input has a visible, persistent `<label>`. Placeholder text is not a
+  label.
+- Required fields are explicitly marked. Optional fields are explicitly
+  marked.
+- Error messages are associated with their inputs via `aria-describedby`.
+- Names: do not require a "first name" + "last name" split. Use a single
+  full-name field. Allow Unicode, spaces, hyphens, apostrophes, and length up
+  to at least 70 characters.
+- Addresses: support international formats. Do not assume US ZIP, US states,
+  or a single-line city/state/zip.
+- Phone numbers: store E.164. Support country codes.
+- Gender: if you must ask, provide a free-text option and "prefer not to
+  say." Do not require it for transactional flows.
+- Date of birth: do not require it unless legally necessary. Support
+  full-range, not just current decade.
+- Never auto-advance focus between inputs unless the user is filling a
+  segmented code field.
+
+---
+
+## 5. Personalization & AI Features
+
+If this app uses AI features (recommendations, summarization, generative
+content, chat):
+
+- Inform users when content is AI-generated.
+- Provide a clear opt-out for AI personalization.
+- Do not use AI features to gate access to core functionality.
+- Surface confidence and uncertainty. Do not present probabilistic output as
+  fact.
+- Do not collect biometric, voice, or facial data without explicit,
+  separately-toggled consent.
+- Preserve user agency: users can edit, reject, or override any AI output.

package/lib/colors.js

@@ -0,0 +1,29 @@
+"use strict";
+
+const supportsColor =
+  process.stdout.isTTY &&
+  process.env.TERM !== "dumb" &&
+  !("NO_COLOR" in process.env);
+
+let enabled = supportsColor;
+
+function set(on) {
+  enabled = on && supportsColor;
+}
+
+function wrap(open, close) {
+  return (s) => (enabled ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+}
+
+module.exports = {
+  set,
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  italic: wrap(3, 23),
+  cyan: wrap(36, 39),
+  magenta: wrap(35, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  red: wrap(31, 39),
+  gray: wrap(90, 39),
+};

package/lib/init.js

@@ -0,0 +1,210 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const c = require("./colors");
+const { createPrompter } = require("./prompt");
+const { loadTemplate, renderGeneric, VARIANTS } = require("./template");
+
+const BANNER = `
+${c.magenta(c.bold("INCLUSION.md"))} ${c.dim("scaffolder")}
+${c.dim("An LLM/agent context convention for model biases - https://github.com/BranonConor/inclusion.md")}
+`;
+
+async function init(args) {
+  c.set(args.color);
+
+  process.stdout.write(BANNER + "\n");
+  process.stdout.write(
+    c.dim(
+      "I'll ask a few questions about your project, then write a customized\n" +
+        "INCLUSION.md to disk. Press Ctrl+C any time to bail.\n"
+    ) + "\n"
+  );
+
+  const p = createPrompter({ acceptDefaults: !!args.yes });
+
+  try {
+    // --- variant ----------------------------------------------------------
+    let variant = args.variant;
+    if (!variant) {
+      variant = await p.choice(
+        "Which template do you want to start from?",
+        [
+          { value: "generic", label: "Generic", hint: "Default. Good for most repos." },
+          {
+            value: "frontend-app",
+            label: "Frontend web app",
+            hint: "Forms, microcopy, AI features.",
+          },
+          {
+            value: "design-system",
+            label: "Design system / component library",
+            hint: "Tokens, components, RTL, density.",
+          },
+          {
+            value: "backend-api",
+            label: "Backend API / SDK",
+            hint: "Schema, errors, auth, telemetry.",
+          },
+        ],
+        { default: 0 }
+      );
+    }
+    if (!VARIANTS[variant]) {
+      throw new Error(
+        `Unknown variant "${variant}". Choose one of: ${Object.keys(VARIANTS).join(", ")}.`
+      );
+    }
+
+    process.stdout.write("\n" + c.bold("Project context") + "\n");
+    process.stdout.write(
+      c.dim(
+        "These answers fill in Section 1. Be specific - generic answers make for generic guidance.\n"
+      ) + "\n"
+    );
+
+    const product = await p.text("What does this project do?", {
+      default: "A short description of what this software does.",
+    });
+    const primaryUsers = await p.text("Who have you intentionally designed for?", {
+      default: "Describe your primary users.",
+    });
+    const underservedUsers = await p.text(
+      "Who do you know you haven't designed for well yet?",
+      {
+        default:
+          "Document a real gap here (e.g. screen reader users on the dashboard; Spanish-language onboarding).",
+      }
+    );
+    const distribution = await p.text(
+      "Where is this software used? (geography, devices, network, assistive tech)",
+      {
+        default:
+          "Web/iOS/Android, primary regions, languages, common assistive technologies.",
+      }
+    );
+    const stakes = await p.text(
+      "What happens when this software excludes someone?",
+      {
+        default:
+          "Describe the real-world cost of exclusion (loss of access to healthcare, employment, civic services, etc.).",
+      }
+    );
+
+    process.stdout.write("\n" + c.bold("Maintenance") + "\n\n");
+
+    const owner = await p.text("Who owns this file? (person or team)", {
+      default: "An accountable person or team",
+    });
+    const cadence = await p.choice(
+      "How often will this file be reviewed?",
+      [
+        { value: "Monthly.", label: "Monthly" },
+        { value: "Quarterly.", label: "Quarterly", hint: "Recommended." },
+        { value: "Twice a year.", label: "Twice a year" },
+        { value: "Annually (minimum).", label: "Annually (minimum)" },
+      ],
+      { default: 1 }
+    );
+    const feedback = await p.text(
+      "How can users and contributors report exclusionary patterns?",
+      {
+        default:
+          "Open an issue on this repository, or contact the owner directly.",
+      }
+    );
+
+    // --- output path ------------------------------------------------------
+    const outPath = path.resolve(
+      process.cwd(),
+      args.out || "INCLUSION.md"
+    );
+
+    if (fs.existsSync(outPath) && !args.force) {
+      const overwrite = await p.confirm(
+        `${path.relative(process.cwd(), outPath) || outPath} already exists. Overwrite?`,
+        { default: false }
+      );
+      if (!overwrite) {
+        process.stdout.write(
+          c.yellow("\nAborted. ") + "Existing file left untouched.\n"
+        );
+        p.close();
+        return;
+      }
+    }
+
+    // --- render -----------------------------------------------------------
+    const template = loadTemplate(variant);
+    const answers = {
+      product,
+      primaryUsers,
+      underservedUsers,
+      distribution,
+      stakes,
+      owner,
+      cadence,
+      feedback,
+    };
+
+    let rendered;
+    if (variant === "generic") {
+      rendered = renderGeneric(template, answers);
+    } else {
+      rendered = prependPersonalizedContext(template, answers);
+    }
+
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, rendered, "utf8");
+
+    p.close();
+
+    const rel = path.relative(process.cwd(), outPath) || outPath;
+    process.stdout.write(
+      "\n" +
+        c.green("✓ ") +
+        c.bold(`Wrote ${rel}`) +
+        c.dim(` (${formatBytes(Buffer.byteLength(rendered))})`) +
+        "\n\n"
+    );
+
+    printNextSteps(rel);
+  } finally {
+    p.close();
+  }
+}
+
+function prependPersonalizedContext(template, answers) {
+  // For non-generic variants, the canonical template already has its own
+  // Section 1. We replace it with the user's answers.
+  return renderGeneric(template, answers);
+}
+
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+function printNextSteps(file) {
+  process.stdout.write(
+    c.bold("Next steps") +
+      "\n\n" +
+      `  1. Open ${c.cyan(file)} and read through it once.\n` +
+      `  2. Point your AI assistant at it:\n\n` +
+      `     ${c.dim("# GitHub Copilot - .github/copilot-instructions.md")}\n` +
+      `     Follow the inclusion guidance in /INCLUSION.md.\n\n` +
+      `     ${c.dim("# Cursor - .cursor/rules/inclusion.md")}\n` +
+      `     Always read and follow /INCLUSION.md.\n\n` +
+      `     ${c.dim("# Claude Code - CLAUDE.md")}\n` +
+      `     Read /INCLUSION.md and apply its review prompts.\n\n` +
+      `  3. Commit it. Treat it like the rest of your engineering docs.\n\n` +
+      c.dim(
+        "Companion essay: https://branon.dev/blog/posts/the-need-for-inclusion-md\n"
+      )
+  );
+}
+
+module.exports = { init };