Capital Framework UI Library

Common errors

• Property -webkit-box-sizing is not supported by autoprefixer. Using legacy prefix instead. Autoprefixer will remove this in a future release.

  cause Using a very old version of Autoprefixer or trying to prefix properties that are no longer standard or automatically handled by modern Autoprefixer versions.
  fix Ensure your `autoprefixer` and `postcss` (if used) dependencies are up-to-date. Configure `browserslist` correctly in your `package.json` or `.browserslistrc` file to specify your target browsers.

• NameError: variable @grid_gutter-width is undefined in ...

  cause A Less variable (e.g., `@grid_gutter-width`) from Capital Framework is missing or not correctly imported/defined, often due to an incomplete or incorrect `@import` path.
  fix Verify that all necessary Capital Framework Less files, especially `cf-core.less` or `capital-framework.less` which define global variables, are correctly imported at the beginning of your main Less file.

• Error: `npm install less less-plugin-autoprefixer` failed with exit code 1

  cause Issues during installation of `less` or `less-plugin-autoprefixer`, potentially due to Node.js version incompatibility, network issues, or corrupted npm cache.
  fix Clear your npm cache (`npm cache clean --force`), ensure you're using a compatible Node.js version, and try installing again. Check npm output for more specific error details related to compilation or peer dependencies.

Warnings

• breaking The entire `capital-framework` project was officially deprecated and archived on July 10, 2020. The repository is read-only, and no further development, bug fixes, or security patches will be provided. Users are strongly advised to migrate to the CFPB's newer design system.
  Fix: Migrate to a actively maintained UI framework or the CFPB's current design system. If continued use is unavoidable, fork the repository and manage maintenance internally.
• breaking Version 1.0.0 changed the build process to use Less `@import` statements for component inclusion instead of Grunt concatenation. This significantly alters how projects should consume and build Capital Framework styles.
  Fix: Update build scripts to use Less compilers that process `@import` directives. Remove any reliance on Grunt for concatenating Capital Framework Less files.
• breaking Version 8.0.0 involved a transition to Lerna for monorepo management. While described as an internal change, this often implies changes in package structure, file paths, or build configurations that could break consumer projects relying on specific internal module layouts or build processes. It affected several sub-packages like `cf-buttons`, `cf-core`, etc.
  Fix: Review project build configurations and Less import paths. Test thoroughly for any broken references or unexpected styling issues resulting from changes in the internal package structure or build process.
• gotcha The compiled Capital Framework CSS will not work perfectly in older browsers without being run through Autoprefixer. The README explicitly warns about this necessity.
  Fix: Always integrate `autoprefixer` into your CSS build pipeline. Ensure it runs after Less compilation but before the CSS is used in production. Example: `lessc --autoprefix=\"> 0.5%, not dead\" input.less output.css`.

Install

• npm install capital-framework npm
• yarn add capital-framework yarn
• pnpm add capital-framework pnpm

Imports

• cf-core
  wrong:

  import { CfCore } from 'capital-framework';

  correct:

  @import "capital-framework/less/cf-core";

  Capital Framework is a CSS/Less library. Core components are included via Less @import statements from the `less/` directory. Direct JavaScript imports for UI components are not how this library is consumed.
• cf-buttons
  wrong:

  require('capital-framework/cf-buttons.css');

  correct:

  @import "capital-framework/less/cf-buttons";

  For specific components like buttons, import their respective Less files. Avoid directly linking to pre-compiled CSS from internal paths as they may lack necessary Autoprefixer processing or global context.
• All components
  wrong:

  import 'capital-framework';

  correct:

  @import "capital-framework/less/capital-framework.less";

  To include all Capital Framework styles, import the main Less file. This should then be compiled to CSS and passed through Autoprefixer. The package does not offer a direct JavaScript entry point for styles.

Quickstart

This quickstart demonstrates how to set up a basic project, compile Capital Framework's Less files to CSS with Autoprefixer, and include the resulting styles in an HTML page. It defines a `package.json` script using `lessc` and showcases importing the main framework Less file, then applying some core styles and components in HTML.

{
  "name": "my-capital-framework-project",
  "version": "1.0.0",
  "description": "Demonstrates basic usage of Capital Framework.",
  "scripts": {
    "build:less": "lessc --autoprefix=\"> 0.5%, not dead\" src/index.less dist/index.css"
  },
  "dependencies": {
    "capital-framework": "^11.0.1",
    "less": "^4.0.0",
    "less-plugin-autoprefixer": "^2.0.0"
  }
}

// src/index.less
@import "../node_modules/capital-framework/less/capital-framework.less";

body {
  padding: 1rem;
}

.wrapper {
  max-width: 960px;
  margin: 0 auto;
  .cf-btn {
    margin-right: 10px;
  }
}

// public/index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Capital Framework Demo</title>
    <link rel="stylesheet" href="./dist/index.css">
</head>
<body>
    <div class="wrapper">
        <h1>Welcome to Capital Framework</h1>
        <button class="cf-btn cf-btn__primary">Primary Button</button>
        <button class="cf-btn cf-btn__secondary">Secondary Button</button>
        <p class="cf-text">This is a paragraph styled by Capital Framework.</p>
    </div>
</body>
</html>