Onboarding: designmodo/Flat-UI

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

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/designmodo/Flat-UI 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.

Verdict

WAIT — Slowing — last commit 10mo ago

• Last commit 10mo ago
• 23+ active contributors
• Distributed ownership (top contributor 17% of recent commits)
• MIT licensed
• ⚠ Slowing — last commit 10mo ago
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

Verify before trusting

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

What it runs against: a local clone of designmodo/Flat-UI — 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 designmodo/Flat-UI | 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 ≤ 332 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>designmodo/Flat-UI</code></summary>

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "designmodo/Flat-UI(\\.git)?\\b" \\
  && ok "origin remote is designmodo/Flat-UI" \\
  || miss "origin remote is not designmodo/Flat-UI (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 "app/css/flat-ui.css" \\
  && ok "app/css/flat-ui.css" \\
  || miss "missing critical file: app/css/flat-ui.css"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "app/css/vendor/bootstrap.min.css" \\
  && ok "app/css/vendor/bootstrap.min.css" \\
  || miss "missing critical file: app/css/vendor/bootstrap.min.css"
test -f ".editorconfig" \\
  && ok ".editorconfig" \\
  || miss "missing critical file: .editorconfig"

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

</details>

TL;DR

Flat UI is a lightweight, flat-design Bootstrap theme (v2.3.0) that provides pre-styled HTML/CSS/SCSS components for rapid web development. It bundles Bootstrap's responsive grid with custom flat-aesthetic overrides across buttons, forms, navigation, and typography—compiled into app/css/flat-ui.css and distributed via npm/Bower for easy integration. Simple source-to-dist build: SCSS source files live in app/styles/ (modules/, mixins/, variables) compiled to app/css/flat-ui.css; Gulp orchestrates compilation, minification, and image optimization via gulpfile.js (not in file list but inferred from devDependencies). Documentation in docs/ directory with examples in docs/examples/. Compiled output copied to dist/ for distribution.

Who it's for

Web designers and front-end developers building responsive websites who want Bootstrap's grid foundation but prefer flat, minimalist UI aesthetics without designing components from scratch. Teams using Bower or npm for dependency management in 2013–2016 era projects.

Maturity & risk

Moderately mature but aging: v2.3.0 is stable and widely used, but the last significant commit activity appears historical (package.json shows no recent bumps). No visible CI/CD pipeline in file list, no test directory found. Production-ready for static/informational websites, but not actively maintained for modern JavaScript frameworks.

High legacy risk: depends on ancient Bower (deprecated 2021), outdated Babel 6, and Bootstrap 2/3-era patterns. No lock files visible suggests potential inconsistent installs. Single maintainer (Designmodo organization) with no visible governance. Breaking changes unlikely since it's frozen, but security updates to dependencies (gulp-uglify, imagemin, etc.) have stalled.

Active areas of work

No active development visible. This is a maintained-but-frozen design system. The repo serves as an archive of a popular 2014–2016 Bootstrap theme. All work is historical; no open PRs or active issues mentioned in provided data.

Get running

git clone https://github.com/designmodo/Flat-UI.git
cd Flat-UI
npm install
bower install

Then run gulp (or specific task like gulp serve) to build and watch. See docs/getting-started.html in browser for integration guide.

Daily commands:

npm install && bower install
gulp serve

This launches BrowserSync on a local dev server watching app/ for changes. Build output goes to dist/ with minified CSS/JS. See exact Gulp tasks in gulpfile.js (not listed but inferred from devDependencies).

Map of the codebase

• app/css/flat-ui.css — Main compiled stylesheet that all contributors must understand—contains the core flat design system styling built on Bootstrap
• package.json — Defines build toolchain (Gulp, Babel, PostCSS) and Node version requirements; essential for setting up local development
• README.md — Entry point for understanding the project's purpose, quick-start options, and getting-started documentation links
• app/css/vendor/bootstrap.min.css — Bootstrap framework dependency that Flat UI extends and customizes; understanding this is prerequisite to modifying components
• .editorconfig — Enforces code formatting consistency across contributors' editors for CSS/LESS/JS files
• CHANGELOG.md — Documents all version changes and breaking updates; critical for understanding design evolution and migration paths

Components & responsibilities

• Bootstrap Grid & Layout (Bootstrap CSS, HTML semantic structure) — Provides responsive 12-column grid, row/column spacing, and breakpoint utilities
  • Failure mode: If Bootstrap CSS is missing or overridden, grid collapses; responsive breakpoints fail
• Flat UI Component Styling (LESS, CSS color variables, compiled flat-ui.css) — Overrides Bootstrap's default component appearance (buttons, cards, forms) with flat design aesthetics
  • Failure mode: If flat-ui.css is not included after bootstrap.css, components revert to Bootstrap's 3D appearance
• Typography System (Lato web fonts (EOT, WOFF, TTF, SVG), @font-face CSS) — Defines font family (Lato), weights, sizes, and line heights for hierarchy and readability
  • Failure mode: If font files fail to load, system fonts substitute; design loses intended aesthetic coherence
• Icon System (flat-ui-pro-icons-regular font files, selection.json mapping) — Custom icon font delivering semantic icons (glyph characters) for UI elements
  • Failure mode: If icon font fails to load, icon placeholders or Unicode characters appear; UI clarity diminished

Data flow

• Developer Source (LESS, HTML, SVGs) → Gulp Build Pipeline — Source files (app/css/.less, docs/.html, app/images/icons/*.svg) are input to build tasks
• Gulp Build Pipeline → Compiled Assets (CSS, JS, Fonts) — LESS → CSS, ES6 → ES5, minification → optimized flat-ui.css, flat-ui.min.js, and font assets
• Compiled Assets → Browser / Demo Pages — HTML files reference compiled flat-ui.css, flat-ui.js, and font files; browser renders flat design components
• Bootstrap Framework → Flat UI CSS Layer — flat-ui.css includes or extends Bootstrap classes; CSS specificity and cascade apply flat design overrides

How to make changes

Add a New Custom Component Style

1. Create a LESS/CSS file in app/css/ for your component (e.g., app/css/my-component.less) (app/css/my-component.less)
2. Import your component LESS file in app/css/flat-ui.css or create a main LESS entry point (app/css/flat-ui.css)
3. Use Gulp build task to compile LESS to CSS (run gulp build or npm run build) (package.json)
4. Add demo HTML examples in docs/examples/ directory to showcase the component (docs/examples/my-component-example.html)

Add a New Icon to the Flat UI Icon Font

1. Create your SVG icon file and place it in app/images/icons/ (app/images/icons/my-icon.svg)
2. Update app/fonts/glyphicons/selection.json to register the new icon mapping (app/fonts/glyphicons/selection.json)
3. Regenerate font files (via Icomoon or equivalent tool) to update .woff, .ttf, .eot, .svg font files (app/fonts/glyphicons/flat-ui-pro-icons-regular.woff)
4. Reference the new icon in CSS using the glyph mapping and test in documentation (app/css/flat-ui.css)

Customize Color Palette or Typography

1. Identify or create a variables/config LESS file (typically defines color variables and font sizes) (app/css/flat-ui.css)
2. Modify color or font variables at the top of flat-ui.css or import a custom variables file (app/css/flat-ui.css)
3. Run Gulp build task to compile changes and regenerate flat-ui.css (package.json)
4. Test changes by opening docs/index.html or a documentation example page in your browser (README.md)

Why these technologies

• Bootstrap — Foundation framework providing responsive grid, components, and utilities; Flat UI enhances and reskins these with flat design
• LESS (CSS preprocessor) — Enables variables, mixins, and code reuse for maintainable color schemes and component styles
• Gulp — Task runner for automating LESS compilation, minification, linting, and browser-sync development server
• Babel — Transpiles ES6+ JavaScript to ES5 for broader browser compatibility in interactive components

Trade-offs already made

• Flat UI extends Bootstrap rather than reinventing from scratch

  • Why: Faster development and guaranteed responsive grid; proven framework with wide adoption
  • Consequence: Tied to Bootstrap's DOM structure and component architecture; customization requires understanding Bootstrap internals

• Static compiled CSS output instead of CSS-in-JS or runtime style injection

  • Why: Simpler deployment, faster initial page load, no runtime overhead
  • Consequence: Theme customization requires rebuild; limited dynamic styling without additional JavaScript

• LESS over SCSS or PostCSS

  • Why: Lightweight, straightforward syntax; popular at time of project creation
  • Consequence: Less ecosystem support compared to SCSS; requires LESS compiler in build chain

Non-goals (don't propose these)

• This is not a JavaScript application framework—it provides no app state management, routing, or MVC scaffolding
• Does not include backend services or APIs—purely a frontend design system
• Not a design tool (Figma, Sketch, etc.)—delivers HTML/CSS/LESS source code and assets only
• Does not provide animation or interaction library beyond basic Bootstrap plugins

Anti-patterns to avoid

• Deep CSS Cascade Dependencies — app/css/flat-ui.css: undefined

Traps & gotchas

1. Bower is deprecated: bower install still works but Bower package manager was sunset in 2021; modern lockfile (package-lock.json / yarn.lock) is absent, risking inconsistent installs across machines.
2. Bootstrap 2/3 only: Flat UI will not work with Bootstrap 4+ due to grid/component API changes; jumping versions breaks layout.
3. No autoprefixer in compiled CSS: gulp-autoprefixer is in devDependencies but unclear if it runs on final dist/ files; test in older browsers (IE10) before shipping.
4. Font paths are relative: app/css/ references ../fonts/ for Lato and icon fonts; moving CSS file breaks font loading unless dist/ structure is preserved.
5. Linting rules are strict: ESLint enforces single quotes in package.json; pull requests with double quotes will fail linting.
6. No environment variables or secrets: Project is frontend-only with no .env requirements, but third-party CDN references in docs may need fallbacks.

Architecture

Concepts to learn

• Flat design — Flat UI's entire aesthetic is built on flat-design principles (no shadows, gradients, or 3D effects); understanding this philosophy is critical to maintaining visual consistency when modifying components
• CSS preprocessor (SCSS/LESS) — Flat UI uses SCSS extensively for variables, mixins, and module organization; you must understand nesting, variable scope, and @import order to modify themes without breaking inheritance
• Bootstrap grid system (float-based) — Flat UI is a Bootstrap theme; all layouts depend on Bootstrap's 12-column float grid (not modern CSS Grid), so responsive design changes must respect col-xs/sm/md/lg breakpoints
• Web font optimization (@font-face, WOFF/TTF) — Flat UI includes 8 Lato font weights + custom icon glyphs via @font-face declarations; understanding font file formats and fallback chains prevents missing icons or broken typography in production
• Gulp task automation — Flat UI's entire build pipeline (SCSS→CSS, minification, image optimization, linting) runs through Gulp; to modify the build process or add steps, you need to understand Gulp 3 task chaining and plugin composition
• CSS vendor prefixes and autoprefixer — Flat UI targets older browsers (IE10+); autoprefixer automatically adds -webkit/-moz prefixes to ensure cross-browser CSS compatibility, but this must run before minification in the Gulp pipeline
• Responsive design breakpoints — Flat UI defines mobile-first media queries via Bootstrap and custom SCSS; all component modifications must account for breakpoints (xs: <768px, sm: 768px, md: 992px, lg: 1200px) to remain responsive

Related repos

• twbs/bootstrap — Flat UI's foundation and parent framework; understanding Bootstrap 3 grid and component API is required to customize Flat UI
• wingrunr21/flat-ui-sass — Community Sass port of Flat UI maintained with better Sass tooling; alternative for projects preferring pure Sass over SCSS-in-Gulp
• daneden/animate.css — Companion library for adding easing/transition effects to Flat UI's static components without additional JavaScript
• designmodo/Slides — Sibling Designmodo framework for presentation/slide builds; shares Flat UI's flat-design philosophy and CSS architecture
• jgthms/bulma — Modern flat-design CSS framework (post-2015) solving the same problem with Flexbox/Grid instead of Bootstrap's float grid; relevant if evaluating whether to migrate from Flat UI

PR ideas

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 GitHub Actions workflow for automated CSS/JS linting and minification verification

The repo has eslint and gulp-based build tools configured (gulp-eslint, gulp-sass, gulp-cssnano, gulp-uglify) but no CI pipeline to verify code quality on PRs. This prevents catching linting errors, unminified assets, or broken builds before merge. A GitHub Action would run gulp tasks and eslint on every PR to ensure app/css/flat-ui.css and compiled JS meet quality standards.

• [ ] Create .github/workflows/build-lint.yml to run 'npm install && gulp lint' on PR
• [ ] Add step to verify app/css/flat-ui.css and minified outputs exist post-build
• [ ] Configure eslint to fail on warnings (currently set to single quotes rule in package.json)
• [ ] Test workflow passes on clean branch before merging

Create Gulp task documentation and fix missing gulpfile.js reference

The package.json references many gulp plugins (gulp-sass, gulp-autoprefixer, gulp-cssnano, gulp-htmlmin, etc.) but there is no gulpfile.js or gulpfile.babel.js in the file structure provided. Contributors cannot understand the build process or add features. A documented gulpfile with clear task separation (build, watch, dist) would improve maintainability and allow contributors to extend the build system.

• [ ] Create gulpfile.babel.js with tasks: 'default' (watch), 'build' (compile LESS/SASS), 'dist' (minify), 'lint' (eslint)
• [ ] Add build task to compile app/css/*.less files to app/css/flat-ui.css using gulp-sass
• [ ] Document each gulp task in README.md under 'Build Process' section with example commands
• [ ] Reference source LESS/SCSS files that should compile (currently missing from file structure)

Add unit tests for flat-ui.css vendor prefixes and responsive behavior using pytest-html or Jest

The repo uses gulp-autoprefixer and gulp-sourcemaps but has no test suite validating that CSS is correctly prefixed for target browsers or that Bootstrap responsive breakpoints work. Contributors may break responsive grid layouts unknowingly. Adding a test suite (Jest for CSS-in-JS validation or HTML/CSS regression tests) would catch regressions in app/css/flat-ui.css and app/css/vendor/bootstrap.min.css integration.

• [ ] Create tests/ directory with CSS regression test suite (using jest-axe for accessibility or puppeteer for visual regression)
• [ ] Add test file: tests/css-vendor-prefixes.test.js to verify -webkit-, -moz-, -ms- prefixes in compiled app/css/flat-ui.css
• [ ] Add test file: tests/responsive-grid.test.js to validate Bootstrap grid breakpoints (xs, sm, md, lg) render correctly
• [ ] Add 'test' script to package.json and integrate into GitHub Actions workflow from PR #1

Good first issues

• Add unit/integration tests for SCSS compilation: create test/ directory with tests verifying app/styles/_variables.scss overrides are correctly applied to compiled app/css/flat-ui.css (e.g., color values, font sizes). Currently no test coverage visible.
• Document migration path from Flat UI Free to Flat UI Pro: create docs/migration-guide.html explaining SCSS variable name changes, new component classes, and breaking CSS selectors. Currently only a README link to the external Sass port (wingrunr21/flat-ui-sass) exists.
• Add TypeScript definitions for custom JavaScript plugins: create index.d.ts or types/ stubs for any vanilla JS components in app/scripts/ to help TypeScript projects consuming the compiled CSS + JS from npm/dist/. Currently no .d.ts files present.

Top contributors

• @andrianvaleanu — 17 commits
• @StefanYohansson — 15 commits
• @pytkin — 11 commits
• @snotr — 9 commits
• @andrew-ml — 9 commits

Recent commits

• cead40a — Update README.md (MonsterCritic)
• aee0708 — Update README.md (MonsterCritic)
• 9ca1608 — Merge pull request #295 from BobConanDev/master (MonsterCritic)
• 55ec44e — Updated CHANGELOG.md, fix typo(s) (NicholasWilsonDEV)
• 901fc0a — Update README.md (andrianvaleanu)
• da7a229 — Update README.md (andrianvaleanu)
• 5f8f803 — Update README.md (andrianvaleanu)
• 0b2a4c8 — Update README.md (andrianvaleanu)
• acba875 — Update README.md (andrianvaleanu)
• 765b800 — Update README.md (andrianvaleanu)

Security observations

Failed to generate security analysis.

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

Where to read next

• 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.