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/neat 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.

WAIT — Stale — last commit 7y ago

• 18 active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MIT licensed
• Tests present
• ⚠ Stale — last commit 7y ago
• ⚠ No CI workflows detected

_{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/neat repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/thoughtbot/neat.

What it runs against: a local clone of thoughtbot/neat — 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/neat | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 2422 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of thoughtbot/neat. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/thoughtbot/neat.git
#   cd neat
#
# 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/neat and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "thoughtbot/neat(\\.git)?\\b" \\
  && ok "origin remote is thoughtbot/neat" \\
  || miss "origin remote is not thoughtbot/neat (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "core/_neat.scss" \\
  && ok "core/_neat.scss" \\
  || miss "missing critical file: core/_neat.scss"
test -f "core/neat/settings/_settings.scss" \\
  && ok "core/neat/settings/_settings.scss" \\
  || miss "missing critical file: core/neat/settings/_settings.scss"
test -f "core/neat/mixins/_grid-column.scss" \\
  && ok "core/neat/mixins/_grid-column.scss" \\
  || miss "missing critical file: core/neat/mixins/_grid-column.scss"
test -f "core/neat/functions/_neat-parse-columns.scss" \\
  && ok "core/neat/functions/_neat-parse-columns.scss" \\
  || miss "missing critical file: core/neat/functions/_neat-parse-columns.scss"
test -f "core/neat/functions/_neat-column-width.scss" \\
  && ok "core/neat/functions/_neat-column-width.scss" \\
  || miss "missing critical file: core/neat/functions/_neat-column-width.scss"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2422 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2392d)"
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/neat"
  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).

Neat is a fluid, float-based Sass grid framework that generates responsive layouts without requiring HTML class scaffolding. It uses Sass mixins (like @include grid-column(6) and @include grid-container) to apply grid logic directly to semantic CSS selectors, solving the problem of maintaining clean HTML while building complex responsive layouts in a pre-CSS-Grid era. Modular Sass architecture: core/_neat.scss imports all framework logic; core/neat/functions/ contains 11 utility functions (e.g., _neat-column-width.scss, _neat-parse-media.scss); core/neat/mixins/ has 8 public mixins (_grid-container.scss, _grid-column.scss, _grid-media.scss, etc.); contrib/patterns/ provides example implementations. Settings live in core/neat/settings/_settings.scss.

Front-end developers and designers building responsive websites with Sass who need a lightweight grid system that keeps layout concerns out of HTML markup. Particularly relevant for Rails developers (4.2+) using the Sprockets asset pipeline and npm users integrating with Node-based build tools via eyeglass.

This project is no longer actively maintained — the README explicitly states "This project is no longer maintained. We favor and encourage people to use native CSS features like Grid and Flexbox." It was production-ready in its heyday (version 4.0.0 in npm) with CI via CircleCI and code review via Hound, but has reached end-of-life as CSS Grid and Flexbox superseded float-based frameworks.

High risk for new projects: Neat is officially deprecated in favor of native CSS Grid/Flexbox. Dependencies are minimal (Sass 3.4+) but the framework itself won't receive security updates or bug fixes. The codebase is stable but unmaintained — any bugs or compatibility issues with future Sass versions will persist. Use only for maintaining legacy codebases, not greenfield projects.

No active development. The repository is in archived/maintenance-only state. No recent commits, PRs, or milestones are visible. The last activity was likely around the 4.0.0 release announcement (per RELEASING.md and CHANGELOG.md patterns).

gem install neat
neat install
# OR for npm:
npm install --save bourbon-neat
# Then import in your Sass:
@import "neat/neat";

Daily commands: Development: npm run contrib (runs gulp per package.json, which uses gulp-sass to compile contrib/styles.scss and serve via browser-sync). Testing: npm test runs bundle exec rake (Ruby test suite). No production runtime needed — Neat is purely a build-time Sass processor.

• core/_neat.scss — Main entry point that imports all Neat functionality; every contributor must understand the module structure and what gets exported
• core/neat/settings/_settings.scss — Defines default grid configuration (columns, gutter, breakpoints); modifications here affect all grid behavior across the framework
• core/neat/mixins/_grid-column.scss — Core mixin that calculates and applies column widths; the most frequently used grid primitive in user code
• core/neat/functions/_neat-parse-columns.scss — Parses user-provided column ratios into usable grid values; critical parsing logic for grid calculations
• core/neat/functions/_neat-column-width.scss — Calculates actual pixel/percentage widths for columns; foundational math for the entire grid system
• spec/spec_helper.rb — Test configuration and helpers; required reading to understand how to add and run tests
• index.js — Node/Eyeglass module entry point; defines how Neat integrates as an npm package and Eyeglass module

Add a new grid mixin

1. Create a new mixin file in core/neat/mixins/_grid-<name>.scss that uses existing functions (core/neat/mixins/_grid-<name>.scss)
2. Import the new mixin in core/_neat.scss (core/_neat.scss)
3. Create test fixtures at spec/fixtures/mixins/grid-<name>.scss showing expected output (spec/fixtures/mixins/grid-<name>.scss)
4. Add RSpec test file at spec/neat/mixins/grid_<name>_spec.rb using Sass compilation matchers (spec/neat/mixins/grid_<name>_spec.rb)
5. Run bundle exec rake to verify tests pass (Rakefile)

Add a new calculation function

1. Create a new function file in core/neat/functions/_neat-<name>.scss that performs grid math (core/neat/functions/_neat-<name>.scss)
2. Import the function in core/_neat.scss if it should be public, or in a mixin if internal-only (core/_neat.scss)
3. Create test fixture at spec/fixtures/functions/neat-<name>.scss with Sass test expressions (spec/fixtures/functions/neat-<name>.scss)
4. Add RSpec tests at spec/neat/functions/neat_<name>_spec.rb that compile fixtures and assert output (spec/neat/functions/neat_<name>_spec.rb)

Add a new configuration setting

1. Add the new key and default value to the $neat-defaults map in core/neat/settings/_settings.scss (core/neat/settings/_settings.scss)
2. Update core/neat/functions/retrieve-neat-settings.scss if custom parsing/merging logic is needed (core/neat/functions/retrieve-neat-settings.scss)
3. Update any mixins that should respect the new setting to call retrieve-neat-settings and use the value (core/neat/mixins/_grid-column.scss)
4. Add test fixtures in spec/fixtures to verify the new setting is read and applied (spec/fixtures/functions/retrieve-neat-settings.scss)
5. Run bundle exec rake to ensure all tests pass (Rakefile)

• Sass/SCSS — Provides mixins, functions, and variables for reusable, composable grid logic; compiles to plain CSS floats
• CSS Floats — Browser-compatible layout primitive that works in legacy and modern browsers without JavaScript
• Ruby Gem + Node npm Package — Dual distribution enables integration with both Rails asset pipeline and modern bundlers (Webpack, Eyeglass)
• RSpec + Sass compilation tests — Verifies generated CSS output matches expectations; catches regressions in grid math and mixin behavior

• Float-based grid instead of CSS Grid or Flexbox
  • Why: Neat predates modern CSS layout features; floats work in older browsers without polyfills
  • Consequence: Less semantic than Grid, requires clearfix hacks, less powerful for 2D layouts; now superseded by native features

No hidden gotchas — this is a straightforward Sass framework. Key constraints: Sass version pinning — must use Sass 3.4+ or LibSass 3.3+ or framework functions will fail silently. Import order matters — settings must be overridden before importing @import "neat/neat" or defaults apply. Float-based layout limitations — clearfix bugs, margin-collapse issues, and alignment quirks are inherent to float layouts, not Neat-specific. Node asset pipelines require eyeglass configuration (see package.json eyeglass field) to resolve the neat module correctly.

• Fluid Grid Systems — Neat's entire design is built on fluid (percentage-based) grids rather than fixed-pixel grids; understanding how fractions translate to percentages is essential to customizing column counts and gutter widths
• CSS Float-Based Layouts — Neat uses floats to position columns side-by-side; modern developers may be unfamiliar with float clearfix tricks, margin-collapse, and float stacking that Neat handles internally
• Sass Mixins and Functions — Neat's entire API is built on Sass mixins (reusable code blocks) and functions (pure calculations); learning Neat requires fluency in @mixin, @include, and @function syntax
• Responsive Design with Media Queries — The grid-media mixin abstracts media query syntax to allow responsive column changes; understanding breakpoints and mobile-first vs desktop-first strategies is core to Neat usage
• CSS Clearfix — The grid-container mixin applies a clearfix to contain floated children; the micro-clearfix technique (using ::before and ::after pseudo-elements) prevents layout collapse
• Semantic HTML and Separation of Concerns — Neat's core philosophy is keeping layout out of HTML classes and putting it in Sass; this required rethinking how grids map markup structure to visual layouts, now solved differently by CSS Grid

• thoughtbot/bourbon — Bourbon is the complementary Sass utility library from the same thoughtbot team; Neat is built to work alongside Bourbon helpers
• sass/sass — Neat depends entirely on Sass 3.4+; understanding Sass functions, mixins, and the @import system is essential to extending Neat
• twbs/bootstrap — Bootstrap's grid system solves the same responsive layout problem but uses semantic HTML classes instead of Sass mixins; represents the class-based alternative to Neat's mixin approach
• mozilla/foundation — Foundation framework is a contemporary float-based grid from the same era (pre-CSS-Grid) that competed with Neat in 2010–2015 projects
• eyeglass/eyeglass — Eyeglass is the Node module system that allows Neat to be imported as npm package in webpack/Rollup builds; critical for non-Rails users

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 unit tests for core grid functions in spec/fixtures/functions

The spec/fixtures directory contains test fixtures for functions like neat-column-default, neat-column-width, neat-float-direction, neat-opposite-direction, and neat-parse-media, but there are no visible test runner files or assertions. The repo has a test script (bundle exec rake) but no spec/spec_helper.rb or similar test infrastructure visible. This is critical for a grid framework where calculation accuracy is essential.

• [ ] Create spec/spec_helper.rb to configure the Sass testing framework (likely sass-spec or similar Ruby-based Sass test runner)
• [ ] Add test files for each function in spec/functions/ (e.g., spec/functions/neat-column-width_spec.scss) with assertions for edge cases: zero columns, fractional columns, custom gutter values
• [ ] Add test file for core/neat/mixins/ to verify grid-column, grid-container, grid-media produce correct CSS output
• [ ] Update Rakefile to run these tests and ensure CI passes

Add GitHub Actions workflow for automated testing across Node.js versions and Ruby versions

The repo uses CircleCI (.circleci/config.yml exists) but there is no visible GitHub Actions workflow file. Since this is a dual-platform package (npm + Ruby gem, shown by package.json and neat.gemspec), contributors should be able to test locally. GitHub Actions with matrix testing would catch issues earlier and be more discoverable for contributors forking the repo.

• [ ] Create .github/workflows/test.yml with Node.js matrix (12.x, 14.x, 16.x, 18.x) to run 'npm test' and 'npm run contrib'
• [ ] Add Ruby version matrix (2.6, 2.7, 3.0, 3.1) to test 'bundle exec rake' and gem functionality
• [ ] Add linting step using existing .hound.yml rules (scss-lint) in the workflow
• [ ] Reference the workflow in README.md's badges section alongside the existing Hound badge

Create missing integration tests for grid media queries in spec/fixtures/functions/neat-parse-media.scss

The file spec/fixtures/functions/neat-parse-media.scss exists but is empty (only listed in structure). The neat-parse-media function is critical for responsive design (grid-media mixin depends on it). Testing edge cases like multiple breakpoints, unitless values, em-based queries, and custom settings is essential but currently untested.

• [ ] Populate spec/fixtures/functions/neat-parse-media.scss with test cases for parsing media query syntax: 'max-width 600px', 'min-width 40em', multiple directives
• [ ] Add tests verifying correct variable substitution from core/neat/settings/_settings.scss values
• [ ] Add tests for error handling (invalid syntax, missing breakpoint definitions)
• [ ] Cross-reference against contrib/patterns/_grid-media.scss to ensure parse output integrates correctly with the mixin

• Add test coverage for core/neat/functions/_neat-opposite-direction.scss — no test file appears in the repo structure, yet this function is critical for RTL (right-to-left) layout support. Write a Sass test that verifies _neat-opposite-direction(left) returns right and vice versa.
• Document the grid-shift and grid-push mixins in README.md with concrete examples — the file list shows contrib/patterns/_grid-push.scss and _grid-shift.scss exist but README only mentions basic grid-column and grid-container. Add a 'Advanced Usage' section with before/after code.
• Fix or document deprecation status in contrib examples — README states the project is unmaintained and users should use CSS Grid, but contrib/patterns/ and contrib/index.html still present Neat as current best practice. Either add a banner to contrib/index.html or add migration guide to CONTRIBUTING.md.

The Neat project has a generally good security posture for a Sass grid framework with no active injection vulnerabilities, hardcoded secrets, or Docker misconfigurations detected. However, the project is unmaintained, and devDependencies are significantly outdated (2-3 years old), which poses medium-level risks in development environments. The codebase itself is relatively simple (SCSS/Sass templating language) with minimal attack surface. Primary concerns are: (1) outdated npm packages that may contain known vulnerabilities, (2) lack of maintenance status meaning no security patches will be applied, and (3) minor insecure protocol usage in documentation. For production use, migration to native CSS Grid/Flexbox is strongly recommended.

• Medium · Outdated DevDependency: browser-sync — package.json - devDependencies. browser-sync version ^2.24.6 is significantly outdated (released ~2018). Modern versions have security patches and bug fixes. This could expose the development environment to known vulnerabilities if used in a development pipeline. Fix: Update browser-sync to the latest stable version: npm update browser-sync. Review changelog for breaking changes.
• Medium · Outdated DevDependency: gulp-sass — package.json - devDependencies. gulp-sass version ^4.0.1 is outdated (released ~2018). Newer versions may contain security improvements and better handling of Sass compilation. Fix: Update gulp-sass to version 5.x or later: npm update gulp-sass. Test for compatibility with build scripts.
• Low · Project Maintenance Status — README.md. The project is explicitly marked as 'no longer maintained' in the README. This means security vulnerabilities or issues will not receive updates or patches from the maintainers. Fix: For new projects, use modern CSS Grid and Flexbox instead. For existing projects using Neat, consider migrating to native CSS solutions or forking the project if continued maintenance is required.
• Low · Insecure Protocol in README — README.md - logo reference. README.md contains an incomplete URL using http:// protocol: 'http://images.thoughtbot.com/bourbon/neat-logo-v2.svg'. Should use https:// for security. Fix: Change 'http://images.thoughtbot.com' to 'https://images.thoughtbot.com' to ensure secure loading of assets.
• Low · No Security Policy or Security Headers Configuration — Repository root. No security.md or security policy file found. No visible security headers configuration or OWASP compliance measures in the codebase. Fix: Create a SECURITY.md file with vulnerability disclosure policy. Consider adding security-related configuration files if this project resumes maintenance.

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.