spaceBase Documentation

The scss/ directory is organized into three functional areas:

• Base: Contains core abstractions like the grid framework, mixins, and helpers. These are the building blocks of spaceBase. While you should not edit these core files, you can extend the framework by adding your own mixins to mixins.scss.
• UI: Contains project-specific styles (typography, forms, buttons, etc.). This is where you should tailor the framework to your specific application and organize your own partials.
• Vendor: Contains third-party dependencies like Normalize. You can add other vendor files here.

spaceBase follows a specific directory structure to separate core logic from custom UI. When building your project, follow this pattern:

• scss/base/: Contains the core of spaceBase. Do not modify these files directly if you want to maintain upgradeability.
• scss/ui/: This is where you should build your custom UI layer.
• scss/_vars.scss: The global configuration file for variables.
• scss/application.scss: The main entry point for your compiled styles.

The behavior of the grid changes based on the $responsive variable in _vars.scss:

• $responsive: false: The grid collapses to 100% width on mobile. Proportional-width classes (e.g., one-half) only apply from the lap breakpoint and above. This is best for simple layouts.
• $responsive: true: Grid proportions remain constant across all breakpoints. You can use breakpoint-prefixed classes to change widths dynamically at different sizes.

Example (Dynamic Layout):

<div class="grid-wrapper">
    <div class="grid one-whole hand-one-half lap-one-third desk-one-quarter">
        ...
    </div>
</div>

In this example, the element is full-width on mobile, half-width on hand, one-third on lap, and one-quarter on desk.

The grid system uses percentage-width flex items with human-readable classnames.

Requirements:

• Every set of grid items must be wrapped in a grid-wrapper.
• Gutters are controlled by $base-sizing-unit (configurable in _vars.scss).

Modifier Classes:

• grid-wrapper--rev: Reverses the order of grid items.
• grid-wrapper--full: Removes gutters between grid items.
• align--center: Aligns grid items.

Example:

<div class="grid-wrapper grid-wrapper--full align--center">
    <div class="grid two-thirds">
        ...
    </div>
    <div class="grid one-third">
        ...
    </div>
</div>

When using spaceBase in a Next.js project, follow these two recommendations for a better developer experience:

1. Set up path aliases

To use cleaner import statements (e.g., @use '@/app/styles/globals' as *;), configure a custom alias in your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

2. Silence Sass deprecation warnings

To suppress warnings related to the "Legacy JS API" in Next.js, update your next.config.js:

module.exports = {
  sassOptions: {
    silenceDeprecations: ['legacy-js-api'],
  },
};

You can install spaceBase via npm or by downloading the ZIP archive. If downloading the ZIP, copy its contents directly into your project folder.

npm install spacebase

All SCSS partials are imported into application.scss. To use spaceBase in your project:

1. Manage Imports: When adding new project-specific partials, add them to the import list in application.scss.
2. Set up Compilation: Configure your Sass compiler to output the generated CSS into the stylesheets/ directory.
3. Production Optimization: Because the source files contain significant comments, always use minified CSS for production builds.

Important: To access global variables, mixins, or variables-based media queries (e.g., @include media($from: lap)) in any new SCSS file, you must include the following line at the very top of the file:

@use '/[path-to-your-styles-directory]/globals' as *;

Push classes move grid items to the right, creating white space on the left. The availability of these classes depends on the $responsive setting:

• If $responsive is false: Push classes only apply from the lap breakpoint and above.
• If $responsive is true: You can use breakpoint-prefixed push classes (e.g., push--lap-three-eighths) for granular control.

Note: To reduce CSS file size, you can disable push styles entirely by setting the corresponding variable to false in _vars.scss.

Example:

<div class="grid-wrapper">
    <div class="grid one-half lap-one-quarter push--one-quarter push--lap-three-eighths">
        ...
    </div>
</div>

Customizable settings for the entire framework are located in _vars.scss. You can use this file to manage:

• Typography: Font styles and sizes.
• Colors: Project color palettes.
• Breakpoints: Responsive breakpoints.
• Sizing: Base sizing measurements.
• Feature Toggles: Switches to include or exclude specific features (like push styles) to manage file size.

Vertical Rhythm: spaceBase uses a $base-spacing-unit (derived from $line-height-ratio) to maintain consistent vertical rhythm. Most block-level elements (headings, lists, paragraphs) use this unit for bottom margins, ensuring that proportions remain intact even if $base-font-size or $base-line-height are changed.