If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/thoughtbot/bourbon shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 23+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live thoughtbot/bourbon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/thoughtbot/bourbon.

What it runs against: a local clone of thoughtbot/bourbon — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in thoughtbot/bourbon | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 633 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of thoughtbot/bourbon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/thoughtbot/bourbon.git
#   cd bourbon
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of thoughtbot/bourbon and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "thoughtbot/bourbon(\\.git)?\\b" \\
  && ok "origin remote is thoughtbot/bourbon" \\
  || miss "origin remote is not thoughtbot/bourbon (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "core/_bourbon.scss" \\
  && ok "core/_bourbon.scss" \\
  || miss "missing critical file: core/_bourbon.scss"
test -f "core/bourbon/library" \\
  && ok "core/bourbon/library" \\
  || miss "missing critical file: core/bourbon/library"
test -f "core/bourbon/utilities" \\
  && ok "core/bourbon/utilities" \\
  || miss "missing critical file: core/bourbon/utilities"
test -f "core/bourbon/validators" \\
  && ok "core/bourbon/validators" \\
  || miss "missing critical file: core/bourbon/validators"
test -f "lib/bourbon.rb" \\
  && ok "lib/bourbon.rb" \\
  || miss "missing critical file: lib/bourbon.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 633 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~603d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/thoughtbot/bourbon"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Bourbon is a pure Sass library of reusable mixins and functions that abstract away browser-specific CSS patterns (prefixes, vendor quirks, responsive utilities). It compiles to zero CSS output at install time and provides human-readable helpers for common style sheet tasks like buttons, text inputs, timing functions, and positioning—dependency-free Sass that works in any project pipeline. Single-package structure: core/ contains the Sass library organized into core/bourbon/library/ (individual mixin/function files like _border-radius.scss, _prefixer.scss) and core/bourbon/helpers/ (utility lists), with core/bourbon/settings/_settings.scss for global config. bin/bourbon provides a CLI for installation. No separate packages or examples directory.

Frontend developers and designers using Sass/SCSS who want to write DRY stylesheets without wrestling with vendor prefixes, cross-browser hacks, or repetitive spacing/sizing patterns. Particularly used in Ruby on Rails projects (4.2+) but applicable to any build system that supports Sass imports.

Deprecated as of September 13, 2024—no longer actively maintained by thoughtbot. This is a complete lifecycle end, not a slow decline; the maintainers published a blog post recommending users migrate to native CSS features. Version 7.3.0 is the final release. CI/CD is set up (CircleCI, GitHub Actions), but the project will receive no further updates.

This library is deprecated and unmaintained—do not adopt it for new projects. Existing projects using Bourbon should treat it as frozen and plan migration off modern native CSS (CSS Grid, Flexbox, CSS variables, native gap, margin/padding shorthands). No dependency safety updates will be issued. Using this in production requires accepting tech debt.

Nothing. The project is archived and unmaintained as of September 2024. The last activity was likely the deprecation notice and related documentation updates. No new PRs, issues, or commits are expected.

git clone https://github.com/thoughtbot/bourbon.git
cd bourbon
bundle install
bundle exec rake

This installs the gem dependencies and runs the test suite (Gherkin feature tests via Cucumber).

Daily commands: This is not a runnable server—it's a library you import. To test locally: bundle exec rake runs the Gherkin test suite. To lint: npm run stylelint. To generate docs: npm run sassdoc.

• core/_bourbon.scss — Main entry point that imports all Bourbon mixins, functions, and utilities—every contributor must understand the overall module structure
• core/bourbon/library — Directory containing 25+ mixins and functions (border-radius, prefixer, position, etc.) that form Bourbon's core API surface
• core/bourbon/utilities — Shared helper functions (directional-property, contrast-ratio, gamma, etc.) that many library mixins depend on
• core/bourbon/validators — Input validation functions (is-color, is-length, is-number) used throughout the library to ensure type safety
• lib/bourbon.rb — Ruby gem integration point; required to understand how Bourbon is packaged and distributed via Rubygems
• eyeglass-exports.js — Node/eyeglass module export configuration; needed to understand npm package distribution and consumption
• README.md — Documents the deprecation status (Sept 2024) and rationale; essential context for all development decisions

Add a new Sass mixin or function to the library

1. Create a new file in core/bourbon/library/_feature-name.scss with @mixin or @function definition (core/bourbon/library/_feature-name.scss)
2. Import your new file in core/_bourbon.scss by adding @forward "bourbon/library/feature-name"; (core/_bourbon.scss)
3. Add a corresponding RSpec test file spec/bourbon/library/feature_name_spec.rb that validates the mixin output (spec/bourbon/library/feature_name_spec.rb)
4. Document the mixin with SassDoc comments (@mixin, @param, @example) for HTML doc generation (core/bourbon/library/_feature-name.scss)

Add a new utility helper function

1. Create @function in core/bourbon/utilities/_helper-name.scss to encapsulate reusable logic (core/bourbon/utilities/_helper-name.scss)
2. Import it in core/_bourbon.scss with @forward "bourbon/utilities/helper-name"; (core/_bourbon.scss)
3. Call the new function from existing library mixins that need its behavior (core/bourbon/library/*.scss)

Add a validator for a new input type

1. Create @function in core/bourbon/validators/_is-type.scss that returns boolean (core/bourbon/validators/_is-type.scss)
2. Import in core/_bourbon.scss with @forward "bourbon/validators/is-type"; (core/_bourbon.scss)
3. Use the validator in library mixins via @if is-type($arg) guards before processing (core/bourbon/library/*.scss)

• Pure Sass (SCSS) — Zero runtime dependencies; Bourbon compiles away completely, leaving only native CSS. Users choose their own Sass toolchain.
• Ruby Gem distribution (Rubygems) — Legacy Rails/Ruby ecosystem support; many projects used Rails asset pipeline or Compass before deprecation
• npm + Eyeglass — Modern Node.js-based tooling support; Eyeglass is a Sass module system that integrates with webpack, Parcel, etc.
• RSpec for testing — Validates that Sass code compiles to correct CSS; integrates with Ruby toolchain and CI (CircleCI)
• SassDoc — Generates documentation from SassDoc comments in mixins; published to bourbon.io

• Dual distribution (Rubygems + npm)

  • Why: Support both legacy Ruby/Rails users and modern Node/webpack users
  • Consequence: Maintainers must ensure parity; coordinates two build pipelines and package versions

• Pure Sass, no JavaScript

  • Why: Guarantees zero runtime overhead and works in any Sass toolchain
  • Consequence: Complex logic (e.g., contrast-ratio math, gamma conversion) implemented in Sass function syntax, less readable than JS

• Lightweight, minimal opinions

  • Why: Let developers customize defaults (font stacks, scales, colors) without overriding
  • Consequence: Some mixins are thin wrappers; benefits come from composition and reuse, not comprehensive out-of-the-box styling

• Monolithic single repo

  • Why: Simplifies versioning; all mixins/utilities released together
  • Consequence: Cannot adopt new features at independent cadences; users wait for major releases

• Not a CSS framework: Bourbon provides no layout system, typography defaults, or component styles—only helpers and utilities.
• Not a reset or normalization: Does not assume opinionated browser defaults or modify global styles.
• Not a runtime library: Compiles away to pure CSS; no JavaScript execution or dynamic behavior.
• Not actively maintained: Project deprecated September 2024; no new features or breaking changes planned.
• Not for modern CSS features: Bourbon was designed when vendor prefixes and IE8 support were critical; modern CSS (Grid, Flexbox, custom properties) are now native.

No hidden traps because the project is deprecated. However: (1) Sass version requirement is Sass 3.4+ or LibSass 3.3+ (old versions may break), (2) The library is imported via @import (Sass native), not npm require—make sure your build system processes Sass, (3) In Rails, you must rename application.css to application.scss and remove Sprockets directives per the README, (4) Modifying files in the installed bourbon/ directory will be overwritten on the next bourbon install or gem upgrade.

• thoughtbot/bitters — Companion library from the same maintainers for Sass baseline styles and typography defaults, often used with Bourbon for a complete design system
• thoughtbot/neat — Grid system library from thoughtbot built on top of Bourbon mixins—provides responsive layout utilities that complement Bourbon's utilities
• sass/dart-sass — The canonical Sass implementation Bourbon targets—if you're troubleshooting Bourbon, understanding how Sass processes @mixin/@function is essential
• eyeglass/eyeglass — Package manager for Sass modules that Bourbon integrates with via eyeglass-exports.js to enable npm-style distribution of Sass libraries
• postcss/autoprefixer — Modern alternative to Bourbon's vendor prefixing approach—Autoprefixer does automatic prefixing post-CSS compilation, making Bourbon's _prefixer.scss less necessary in contemporary workflows

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive SassDoc documentation for all library mixins and functions

The repo has a sassdoc npm script that validates documentation, but many mixins in core/bourbon/library/ lack complete SassDoc comments. Given the project is deprecated but still widely used, comprehensive inline documentation would help users understand each helper's parameters, return values, and usage examples. This directly supports the existing CI/CD pipeline (npm run sassdoc with --strict flag).

• [ ] Add SassDoc comment blocks to core/bourbon/library/_border-*.scss files (border-color, border-radius, border-style, border-width)
• [ ] Add SassDoc comment blocks to core/bourbon/library/ utility files like _prefixer.scss, _value-prefixer.scss, _shade.scss, and _tint.scss with @param, @return, and @example annotations
• [ ] Run npm run sassdoc in strict mode to validate all documentation meets standards
• [ ] Verify generated documentation appears correctly on bourbon.io/docs/

Add unit tests for validator functions in core/bourbon/validators/

The validators directory contains critical utility functions (_is-color.scss, _is-length.scss, _is-number.scss, _is-size.scss, _contains.scss, _contains-falsy.scss) that validate input to other mixins, but there's no visible test suite in the file structure. Adding Sass unit tests would catch regressions, especially important given the project's deprecation status where maintenance is limited. Tests should use a Sass testing framework like True.

• [ ] Set up True testing framework in the Rakefile or as a separate test task
• [ ] Create test files for core/bourbon/validators/_is-color.scss, _is-number.scss, _is-length.scss, and _is-size.scss with edge cases (null, empty, invalid types)
• [ ] Add tests for core/bourbon/validators/_contains.scss and _contains-falsy.scss with various input arrays
• [ ] Integrate validator tests into the existing bundle exec rake test command

Create GitHub Actions workflow to test Bourbon across different Sass versions

The repo uses CircleCI but lacks a GitHub Actions workflow to test compatibility across Dart Sass, Lib Sass, and different versions. Given Sass itself is actively maintained and Bourbon is a Sass library, ensuring compatibility across Sass implementations would be valuable for the deprecated-but-still-used library. The eyeglass-exports.js integration suggests npm/Node.js tooling is already in place.

• [ ] Create .github/workflows/sass-compat.yml to test against multiple Sass versions (latest Dart Sass, latest LibSass via node-sass, and at least 1.0+)
• [ ] Add a test matrix in the workflow to run npm run stylelint and npm run sassdoc across Sass versions
• [ ] Verify bourbon compiles without errors using each Sass version by adding a simple test SCSS file that imports core/_bourbon.scss
• [ ] Document supported Sass versions in README.md and CONTRIBUTING.md based on test results

• Migrate an existing Bourbon mixin to a concrete native CSS alternative and document it in a pull request to CONTRIBUTING.md—e.g., show how to replace _position.scss (absolute/relative/fixed shorthand) with native CSS position + inset properties.
• Add test coverage for the _modular-scale.scss mixin if it's missing—write a .feature Gherkin test that validates the scale function returns correct ratios for Golden Ratio, Major Third, and other standard scales.
• Expand the stylelint configuration (.stylelintrc.json) to enforce Sass-specific linting rules (e.g., no nested selectors beyond 3 levels, no !important) and document the rationale in CONTRIBUTING.md.

The Bourbon project presents significant security concerns primarily due to its deprecated and unmaintained status combined with severely outdated dependencies. While the codebase itself (Sass/SCSS) has low inherent injection risk, the development dependencies contain known vulnerabilities that will never be patched. Users should not adopt this project for new work and should plan migration to native CSS or actively maintained alternatives. Existing users face increasing security risk over time as more CVEs are disclosed against the old dependency versions.

• High · Outdated Dependencies with Known Vulnerabilities — package.json - devDependencies. The project uses stylelint 10.1.0 (released 2019) and sassdoc 2.5.0 (released 2018). These versions are significantly outdated and likely contain known security vulnerabilities. stylelint 10.1.0 is 5+ years old and has numerous CVEs reported against it and its dependencies. Fix: Update all dependencies to their latest stable versions. Run 'npm audit' to identify specific vulnerabilities and update stylelint to at least v15+ and sassdoc to the latest available version. Implement automated dependency updates using dependabot or similar tools.
• High · Project Marked as Deprecated and Unmaintained — README.md. The README clearly states the project is 'no longer maintained' as of September 13, 2024. This means security patches and vulnerability fixes are not being released. Any newly discovered vulnerabilities will not be addressed. Fix: Users should migrate to modern native CSS features as recommended. For existing users, consider forking the project or switching to actively maintained alternatives. If continued use is necessary, establish internal security review processes.
• Medium · Permissive NPM Eyeglass Configuration — package.json - eyeglass.needs. The eyeglass configuration specifies 'needs': '', which indicates the package requires any version of its dependencies. This could allow installation of incompatible or vulnerable versions during npm install. Fix: Specify explicit version constraints for eyeglass dependencies instead of using wildcard ''. This provides better control over which versions are installed and reduces exposure to unexpected breaking changes or vulnerabilities.
• Low · Missing npm Package Security Configuration — package.json root level. The package.json lacks a 'engines' field specifying required Node.js and npm versions, and there's no '.npmrc' file visible with security settings. This could allow installation in insecure or incompatible environments. Fix: Add 'engines' field specifying minimum Node.js version (e.g., '>=14.0.0'). Create a .npmrc file with security settings like 'audit-level=moderate'. Consider adding 'npm audit' to CI/CD pipeline to catch vulnerabilities before release.
• Low · Limited Vulnerability Disclosure Process — SECURITY.md. While a SECURITY.md file exists, it redirects to a general thoughtbot security page. The deprecation status may affect response times to security reports for this specific project. Fix: Update SECURITY.md to explicitly state that this project is unmaintained and recommend users not report new vulnerabilities. Direct security concerns to the main thoughtbot security contact with clear expectations about response timelines.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.