DBGrid 4.0.95

A Small but Powerful SASS Library for Modern Web Development

DBGrid is a lightweight, flexible SASS library that provides responsive utilities, grid systems, and helpful mixins to accelerate your web development workflow.

📦 Installation

Using npm:

npm install dbgrid

Using yarn:

yarn add dbgrid

🚀 Quick Start

1. SASS Projects (Recommended)

Import DBGrid in your main SASS file:

// main.scss
@use "dbgrid" as *;

// Now you can use all DBGrid features
.container {
  @include flexbox;
  
  @include since(md) {
    padding: 2rem;
  }
}

2. CSS Projects

Use the pre-compiled CSS:

<!-- In your HTML -->
<link rel="stylesheet" href="node_modules/dbgrid/dist/v4/app.css">

Or import in your CSS:

@import "node_modules/dbgrid/dist/v4/app.css";

⚙️ Configuration

Recommended Pattern: Config File with @forward

Create a central config file that overrides DBGrid variables:

// src/scss/_config.scss
@use "dbgrid" as * with (
  $colors: (
    primary: #1854d4,
    secondary: #181818,
    white: #ffffff,
    black: #000000,
    danger: #c51533,
    warning: #ffae00,
    info: #157bc5,
    success: #00c850,
    // Add your custom colors
  ),
  $radius-sizes: (
    xs: 4px,
    sm: 8px,
    md: 12px,
    lg: 16px,
    fluid: 5rem,
  ),
  $tones: (
    5%,
    10%,
    15%,
    20%,
    25%,
    30%,
  )
);

// Forward DBGrid to make it available to other files
@forward "dbgrid";

// Initialize DBGrid helpers
@include reset-styles;
@include util-helpers;
@include layout-helpers;
@include component-helpers;
@include create-color-palette;
@include font-helpers;

Then in other SCSS files, use your config:

// src/scss/_modal.scss
@use "config" as *;

.modal {
  background: get-color(white);
  border-radius: 12px;
  
  @include since(md) {
    padding: 2rem;
  }
}

Or use selective @forward:

// src/scss/_buttons.scss
@use "config" as *;
@forward "dbgrid" show get-color, lighten, since, until;

.button {
  background: get-color(primary);
  
  &:hover {
    background: lighten(get-color(primary), 10%);
  }
}

Available Configuration Variables

| Variable | Default | Description | |----------|---------|-------------| | $columns | 20 | Number of grid columns | | $unity | 16px | Base unit for calculations | | $font-base | 16px | Base font size | | $font-line-height | 1.5 | Base line height | | $breakpoints | See above | Responsive breakpoints map | | $colors | See below | Color palette map | | $spacing-scale | See below | Spacing scale map |

📐 Breakpoints System

DBGrid uses a mobile-first approach with 7 breakpoints:

| Breakpoint | Value | Usage | |------------|-------|-------| | xs | 320px | Mobile portrait | | sm | 768px | Tablet portrait | | md | 1024px | Tablet landscape / Small desktop | | lg | 1366px | Desktop | | xl | 1540px | Large desktop | | 2xl | 1920px | Full HD | | w | 2200px | Wide screens |

🎨 Colors System

Default Color Palette

$colors: (
  primary: #2842eb,
  secondary: #2df20f,
  white: #ffffff,
  black: #181818,
  danger: #c51533,
  warning: #ffae00,
  info: #157bc5,
  success: #00c850,
  smoke: #2842eb,
  light: #ffffff,
  dark: #181818,
);

Using Color Functions

.button {
  // Get color from palette
  background: get-color(primary);
  
  // Adjust colors
  border-color: darken(get-color(primary), 10%);
  
  &:hover {
    background: lighten(get-color(primary), 10%);
  }
}

Auto-generated Color Variables

DBGrid automatically generates CSS variables with tones:

:root {
  --db-primary: #2842eb;
  --db-primary-lighten-10: #...;
  --db-primary-lighten-20: #...;
  --db-primary-darken-10: #...;
  --db-primary-darken-20: #...;
}

🔧 Mixins Reference

1. Responsive Mixins

@include since($breakpoint)

Creates a min-width media query (mobile-first).

.component {
  padding: 1rem;
  
  @include since(sm) {
    padding: 2rem;
  }
  
  @include since(md) {
    padding: 3rem;
  }
}

// Compiles to:
// .component { padding: 1rem; }
// @media (min-width: 768px) { .component { padding: 2rem; } }
// @media (min-width: 1024px) { .component { padding: 3rem; } }

@include until($breakpoint)

Creates a max-width media query.

.mobile-only {
  display: block;
  
  @include until(md) {
    display: none;
  }
}

2. Layout Mixins

@include flexbox

Applies flex display with full width.

.container {
  @include flexbox;
  // Result: display: flex; width: 100%;
}

@include flex-center

Centers content using flexbox.

.centered-content {
  @include flexbox;
  @include flex-center;
  // Result: align-items: center; justify-content: center; align-content: center;
}

3. Font Mixins

@include adaptive-font($min, $max, $direction)

Creates responsive font sizes based on breakpoints.

.title {
  @include adaptive-font(1.5, 3, "up");
}

@include responsive-font($map)

Applies different font sizes at specific breakpoints.

.heading {
  @include responsive-font((
    xs: 16px,
    md: 20px,
    lg: 24px
  ));
}

4. Utility Mixins

@include hover

Styles hover state (excludes disabled elements).

.button {
  background: blue;
  
  @include hover {
    background: darkblue;
  }
}

@include disabled

Styles disabled state.

.button {
  @include disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
}

@include prefix($property, $value)

Adds vendor prefixes automatically.

.element {
  @include prefix(transform, rotate(45deg));
  // Result: -webkit-transform, -moz-transform, -ms-transform, transform
}

@include icon-size($size)

Sets consistent icon dimensions.

.icon {
  @include icon-size(24px);
  // Result: width, height, min-width, min-height: 24px
}

🧮 Functions Reference

Grid Functions

grid($cols, $total: $columns)

Calculates percentage width for grid columns.

.col-6 {
  width: grid(6, 20); // 30%
}

Color Functions

get-color($name)

Retrieves color from palette.

.element {
  color: get-color(primary);
}

lighten($color, $amount) / darken($color, $amount)

Adjusts color brightness.

.button {
  background: lighten(get-color(primary), 10%);
}

Spacing Functions

spacing($key)

Gets spacing value from scale.

.card {
  padding: spacing(md); // 16px
}

// Available: xs(4px), sm(8px), md(16px), lg(24px), xl(32px), xxl(48px)

shadow($key)

Gets predefined shadow.

.card {
  box-shadow: shadow(md);
}

// Available: xs, sm, md, lg, fluid

Conversion Functions

to-rem($pixels)

Converts pixels to rem.

.element {
  margin: to-rem(24px); // 1.5rem
}

🎯 Practical Examples

Example 1: Responsive Card Component

@use "dbgrid" as *;

.card {
  @include flexbox;
  flex-direction: column;
  padding: spacing(md);
  border-radius: 12px;
  background: get-color(white);
  box-shadow: shadow(sm);
  
  @include since(sm) {
    padding: spacing(lg);
  }
  
  @include since(md) {
    flex-direction: row;
    padding: spacing(xl);
  }
  
  @include hover {
    box-shadow: shadow(md);
    transform: translateY(-2px);
  }
}

.card__image {
  @include icon-size(100%);
  border-radius: 8px;
  
  @include since(md) {
    max-width: 300px;
  }
}

.card__title {
  @include responsive-font((
    xs: 18px,
    md: 22px,
    lg: 26px
  ));
  color: get-color(black);
  margin-bottom: spacing(sm);
}

Example 2: Responsive Grid Layout

@use "dbgrid" as *;

.grid-container {
  @include flexbox;
  flex-wrap: wrap;
  gap: spacing(md);
}

.grid-item {
  width: grid(20); // 100% mobile
  
  @include since(sm) {
    width: grid(10); // 50% tablet
  }
  
  @include since(md) {
    width: grid(6, 20); // 30% desktop (6 of 20 columns)
  }
  
  @include since(lg) {
    width: grid(5); // 25% large desktop
  }
}

Example 3: Button Component

@use "dbgrid" as *;

.btn {
  @include flexbox;
  @include flex-center;
  padding: spacing(sm) spacing(lg);
  border: none;
  border-radius: 8px;
  font-weight: 600;
  cursor: pointer;
  transition: all 0.3s ease;
  
  @include hover {
    transform: scale(1.05);
  }
  
  @include disabled {
    opacity: 0.5;
    transform: none;
  }
}

.btn--primary {
  background: get-color(primary);
  color: get-color(white);
  
  @include hover {
    background: darken(get-color(primary), 10%);
  }
}

.btn--secondary {
  background: get-color(secondary);
  color: get-color(black);
  
  @include hover {
    background: darken(get-color(secondary), 10%);
  }
}

Example 4: Real-World Project Setup (Recommended)

Step 1: Create config file

// src/scss/_config.scss
@use "dbgrid" as * with (
  $colors: (
    primary: #1854d4,
    secondary: #181818,
    white: #ffffff,
    black: #000000,
    smoke: #e5e7eb,
    dark: #262626,
    gray: #4b5563,
    danger: #c51533,
    warning: #ffae00,
    info: #157bc5,
    success: #00c850,
  ),
  $radius-sizes: (
    xs: 4px,
    sm: 8px,
    md: 12px,
    lg: 16px,
    fluid: 5rem,
  ),
  $tones: (5%, 10%, 15%, 20%, 25%, 30%, 35%, 40%, 45%, 50%)
);
@forward "dbgrid";

@include reset-styles;
@include util-helpers;
@include layout-helpers;
@include component-helpers;
@include create-color-palette;
@include font-helpers;

Step 2: Create component styles

// src/scss/_modal.scss
@use "config" as *;

.ui\:modal {
  @include flexbox;
  @include flex-center;
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  z-index: 1000;
  
  &__content {
    background: get-color(white);
    border-radius: 12px;
    padding: spacing(lg);
    max-width: 500px;
    width: 90%;
    
    @include since(md) {
      padding: spacing(xl);
    }
  }
}

// src/scss/_inputs.scss
@use "config" as *;
@forward "dbgrid" show get-color, lighten;

.input {
  padding: spacing(sm) spacing(md);
  border: 1px solid get-color(gray);
  border-radius: 8px;
  
  &:focus {
    border-color: get-color(primary);
    outline: none;
  }
  
  &.error {
    border-color: get-color(danger);
  }
}

Step 3: Main entry point

// src/scss/base.scss
@use "./config" as *;
@use "./modal" as *;
@use "./inputs" as *;
@use "./fonts" as *;

:root {
  scroll-behavior: smooth;
}

body {
  font-family: system-ui, -apple-system, sans-serif;
  line-height: 1.6;
}

Example 5: Complete Page Layout

@use "dbgrid" as *;

.page {
  @include flexbox;
  flex-direction: column;
  min-height: 100vh;
}

.header {
  @include flexbox;
  align-items: center;
  justify-content: space-between;
  padding: spacing(md);
  background: get-color(white);
  box-shadow: shadow(sm);
  
  @include since(md) {
    padding: spacing(lg) spacing(xl);
  }
}

.main-content {
  flex: 1;
  padding: spacing(lg) spacing(md);
  
  @include since(md) {
    padding: spacing(xl);
  }
}

.footer {
  padding: spacing(lg) spacing(md);
  background: get-color(dark);
  color: get-color(white);
  text-align: center;
}

📱 Utility Classes

When using the compiled CSS, you get utility classes:

Spacing Classes

<!-- Margin -->
<div class="m:1">margin: 0.5rem</div>
<div class="mt:2">margin-top: 1rem</div>
<div class="mv:3">margin-block: 1.5rem</div>
<div class="mh:4">margin-inline: 2rem</div>

<!-- Padding -->
<div class="p:1">padding: 0.5rem</div>
<div class="pt:2">padding-top: 1rem</div>
<div class="pv:3">padding-block: 1.5rem</div>
<div class="ph:4">padding-inline: 2rem</div>

<!-- Responsive -->
<div class="p:2 md--p:4">Responsive padding</div>

Visibility Classes

<div class="hide:xs">Hidden on mobile</div>
<div class="hide:md">Hidden on desktop</div>
<div class="show:lg">Visible only on large screens</div>

🏗️ Architecture

DBGrid Package Structure

dbgrid/
├── scss/
│   ├── _config.scss          # Configuration variables
│   ├── core/
│   │   ├── functions/        # SASS functions
│   │   │   ├── _base.scss    # Core functions
│   │   │   ├── _colors.scss  # Color functions
│   │   │   └── _utils.scss   # Utility functions
│   │   ├── mixins/           # SASS mixins
│   │   │   ├── _responsive.scss  # since/until mixins
│   │   │   ├── _layout.scss      # Layout mixins
│   │   │   ├── _colors.scss      # Color mixins
│   │   │   ├── _fonts.scss       # Font mixins
│   │   │   └── _utils.scss       # Utility mixins
│   │   └── helpers/          # Helper utilities
│   │       ├── _spacing.scss # Spacing helpers
│   │       ├── _gap.scss     # Gap utilities
│   │       └── _hide.scss    # Visibility helpers
│   ├── interfaces/           # Pre-built components
│   └── utils/                # Utility styles
├── dist/                     # Compiled CSS
└── _index.scss               # Main entry point

Recommended Project Structure

your-project/
├── src/
│   └── scss/
│       ├── _config.scss      # Your DBGrid config (override variables)
│       ├── _modal.scss       # Use config for modals
│       ├── _inputs.scss      # Use config for inputs
│       ├── _buttons.scss     # Use config for buttons
│       └── base.scss         # Main entry (imports all)

Example workflow:

// 1. _config.scss - Override DBGrid
@use "dbgrid" as * with ($colors: (...));
@forward "dbgrid";
@include create-color-palette;

// 2. _modal.scss - Use your config
@use "config" as *;
.modal { background: get-color(white); }

// 3. base.scss - Import everything
@use "./config";
@use "./modal";
@use "./inputs";

🎓 Best Practices

1. Use Module System

// ✅ CORRECT - Modern SASS
@use "dbgrid" as *;

// ❌ WRONG - Deprecated
@import "dbgrid";

2. Override Variables with Config File

// ✅ CORRECT - Central config file
// _config.scss
@use "dbgrid" as * with (
  $colors: (
    primary: #your-color
  )
);
@forward "dbgrid";

// other-file.scss
@use "config" as *;

// ❌ WRONG - Override after import
$colors: (...);
@use "dbgrid";

3. Mobile-First Approach

// ✅ CORRECT - Mobile first
.element {
  width: 100%;
  
  @include since(md) {
    width: 50%;
  }
}

// ❌ WRONG - Desktop first
.element {
  width: 50%;
  
  @include until(md) {
    width: 100%;
  }
}

4. Use Spacing Scale

// ✅ CORRECT - Consistent spacing
padding: spacing(md);
margin: spacing(lg);

// ❌ WRONG - Magic numbers
padding: 18px;
margin: 27px;

🔍 Troubleshooting

Issue: "Color not found"

Solution: Make sure the color exists in your $colors map.

Issue: "Breakpoint not defined"

Solution: Check that you're using valid breakpoints: xs, sm, md, lg, xl, 2xl, w.

Issue: "@import is deprecated"

Solution: Use @use "dbgrid" as *; instead of @import.

Issue: "Can't override variables"

Solution: Create a central _config.scss file with @use "dbgrid" as * with (...) and @forward "dbgrid", then import your config in other files with @use "config" as *;

📚 Resources

• Repository: https://gitlab.com/leoquintara/dbgrid
• Issues: https://gitlab.com/leoquintara/dbgrid/issues
• Author: Leonardo Quintana Juarez
• License: MIT

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

MIT License - feel free to use in your projects!

Made with ❤️ by Leonardo Quintana