visipix.css

visipix.css is a lightweight CSS utility library (compiled from SCSS) for creating user interfaces.

The package contains the utilities and small component hooks needed to compose UIs. It is renderer‑agnostic and can be used with any framework (React, Vue, Svelte) or plain HTML.

• Paradigm: Utility‑first helpers plus light component hooks
• Themes: Auto light/dark via CSS variables (prefers-color-scheme)

Table of Contents

• Installation
• Getting started
• Layout and display
  • Grid columns
• Spacing and gap scale
• Sizing utilities
  • Containers
• Positioning and z-index
• Borders and radius
• Typography
• Colors and backgrounds
• Transitions and effects
• Components
  • Buttons
  • Dropdown menu
  • Carousel (infinite slider)
  • Loader
  • Forms
  • Modal
  • Transitions
• Theming
• Examples: quick layouts
• Notes

Installation

# npm
echo "Using npm" && npm install visipix.css

# yarn
yarn add visipix.css

# pnpm
pnpm add visipix.css

Getting started

Include the compiled CSS in your app/site (no SCSS bundler required):

// JavaScript/TypeScript entry
import 'visipix.css' // resolves to prebuilt CSS via package exports

Note: This package ships prebuilt CSS (dist/visipix.css). The SCSS source is excluded from the npm package.

CSS variables are applied on html using the user's preferred color scheme. You can rely on:

• --primary__color
• --secondary__color
• --border, --gray, --red, --blue, --yellow, --shadow, --overlay

Layout and display

| Class | Effect | |---|---| | d__flex | display: flex | | d__grid | display: grid | | d__block | display: block | | d__inline-block | display: inline-block | | flex__row | flex-direction: row; plus responsive mobile helpers (see below) | | flex__col | flex-direction: column; plus responsive mobile helpers | | flex__wrap | flex-wrap: wrap | | flex__grow | flex-grow: 1 | | justify__start/center/end/between | justify-content variants; mobile overrides via m__justify--* | | align__start/center/end | align-items variants; mobile overrides via m__align--* |

Display and visibility helpers

| Class | Description | Breakpoint/Notes | |---|---|---| | d__none | display: none !important | Always | | d__none--scrollbar | Hides the element's WebKit scrollbar; content remains scrollable | WebKit only | | hide__desktop | Hide on desktop | >= 1024px | | hide__tablet__desktop | Hide on tablet and desktop | >= 768px | | hide__mobile__tablet | Hide on mobile and tablet | <= 1024px | | hide__mobile | Hide on mobile | <= 768px |

Responsive override helpers (mobile ≤ 768px)

| Class pattern | Effect on small screens | |---|---| | m__flex--row | Force flex-direction: row | | m__flex--col | Force flex-direction: column | | m__justify--start/center/end/between | Override justify-content | | m__align--start/center/end | Override align-items | | m__text--l/c/r/justify | Override text alignment |

Grid columns

Create responsive grid columns with .grid__N where N = 0..512 (configurable). Automatically adapts to breakpoints; force a fixed count with fixed__N on the same element.

<div class="d__grid grid__4 g__16">
  <div>Item</div>
  <div>Item</div>
</div>
<!-- On laptop/tablet/mobile, the column count gracefully scales down -->
<!-- Add fixed__4 to keep 4 columns across breakpoints -->

Spacing and gap scale

For i = 0..512 by default (interpreted as pixels then converted to rem via a 16px base). This maximum is configurable in SCSS via $utilities-max.

Gap utilities

| Utility | Range | Example | Result | |---|---|---|---| | g__i | 0..512 | g__16 | gap: 1rem | | g__r--i | 0..512 | g__r--24 | row-gap: 1.5rem | | g__c--i | 0..512 | g__c--8 | column-gap: 0.5rem |

Padding utilities

| Utility | Range | Example | Result | |---|---|---|---| | p__i | 0..512 | p__16 | padding: 1rem | | p__t--i / p__r--i / p__b--i / p__l--i | 0..512 | p__b--24 | padding-bottom: 1.5rem |

Margin utilities

| Utility | Range | Example | Result | |---|---|---|---| | m__i | 0..512 | m__12 | margin: 0.75rem | | m__t--i / m__r--i / m__b--i / m__l--i | 0..512 | m__b--24 | margin-bottom: 1.5rem |

Sizing utilities

Exact sizing (rem)

| Utility | Range | Example | Result | |---|---|---|---| | w__i | 0..512 | w__256 | width: 16rem | | h__i | 0..512 | h__128 | height: 8rem |

Percentage sizing

| Utility | Range | Example | Result | |---|---|---|---| | w__i--% | 0..100 | w__50--% | width: 50% | | h__i--% | 0..100 | h__100--% | height: 100% |

Viewport height

| Utility | Range | Example | Result | |---|---|---|---| | dvh__i | 0..100 | dvh__90 | height: 90dvh |

Min/Max sizing

| Utility | Range | Example | Result | |---|---|---|---| | min__w--i | 0..512 | min__w--320 | min-width: 20rem | | max__w--i | 0..512 | max__w--640 | max-width: 40rem | | min__h--i | 0..512 | min__h--64 | min-height: 4rem | | max__h--i | 0..512 | max__h--512 | max-height: 32rem |

Full and fit utilities

| Utility | Effect | |---|---| | w__max | width: 100% | | h__max | height: 100% | | min__w--full | min-width: 100% | | max__w--full | max-width: 100% | | min__h--full | min-height: 100% | | max__h--full | max-height: 100% | | w__fit-content | width: fit-content | | h__fit-content | height: fit-content |

Containers

Centered, fixed-width containers:

• container__xxl, container__xl, container__lg, container__md, container__sm, container__xs

Example:

<header class="bg__secondary color__light">
  <div class="container__md p__16">
    <h1 class="m__0">Brand</h1>
  </div>
</header>

<main class="p__16">
  <div class="container__md d__grid grid__3 g__16">
    <article class="p__16 bg__light rounded__8">Card A</article>
    <article class="p__16 bg__light rounded__8">Card B</article>
    <article class="p__16 bg__light rounded__8">Card C</article>
  </div>
</main>

Positioning and z‑index

Position

| Class | Effect | |---|---| | p__absolute | position: absolute | | p__relative | position: relative | | p__fixed | position: fixed | | p__sticky | position: sticky | | p__static | position: static |

Offsets (i = 0..512)

| Pattern | Example | Result | |---|---|---| | top__i | top__16 | top: 1rem | | right__i | right__24 | right: 1.5rem | | bottom__i | bottom__8 | bottom: 0.5rem | | left__i | left__32 | left: 2rem | | -top__i / -right__i / -bottom__i / -left__i | -left__16 | left: -1rem |

Z-index

| Pattern | Range | Example | Result | |---|---|---|---| | z__i | any integer | z__10 | z-index: 10 | | -z__i | any integer | -z__1 | z-index: -1 |

Overflow and pointer events

| Class | Effect | |---|---| | overflow__hidden | overflow: hidden | | overflow__x-auto | overflow-x: auto | | overflow__y-auto | overflow-y: auto | | pointer__events--none | pointer-events: none |

Borders and radius

Radius utilities

| Utility | Description | Range/Notes | |---|---|---| | rounded__max | Full round (circle) | 100% border-radius | | rounded__i | Uniform radius | i = 0..512 (Rem scaled) | | rounded__t-r-i / rounded__t-l-i | Top-right / Top-left radius | i = 0..512 | | rounded__b-r-i / rounded__b-l-i | Bottom-right / Bottom-left radius | i = 0..512 |

Border utilities

| Utility | Description | Range/Notes | |---|---|---| | border__i | Full border width using theme border color | i = 0..512; width = i/2 rem | | border__t--i / border__r--i / border__b--i / border__l--i | Side-specific border | i = 0..512; width = i/2 rem | | border__primary / border__secondary / border__danger / border__info / border__dark / border__light / border__blue / border__yellow / border__green | Color modifiers (combine with any border class) | Applies themed color |

Example:

<div class="border__8 border__secondary rounded__12"></div>

Typography

Headings

| Element | Default size (approx) | Responsive behavior | |---|---|---| | h1 | 96px | Scales to 54px on large mobile | | h2 | 70px | Scales to 36px on large mobile | | h3 | 34px | Scales to 26px on large mobile | | h4 | 24px | — | | h5 | 20px | — |

Text sizing

| Class | Size | |---|---| | font__lg | 18px | | font__md | 16px | | font__sm | 14px |

Weights and spacing

| Pattern/Class | Range/Example | Effect | |---|---|---| | weight__i | i = 0..1000 step 100 | font-weight: i | | line__h--i | i = 0..512 | line-height: Rem(i) | | letter__s--i | i = 0..512 | letter-spacing: Rem(i) | | -letter__s--i | i = 0..512 | letter-spacing: -Rem(i) |

Transforms and alignment

| Class | Effect | |---|---| | text__uppercase | text-transform: uppercase | | text__capitalize | text-transform: capitalize | | text__l / text__c / text__r / text__justify | text-align: left/center/right/justify; mobile overrides: m__text--l/c/r/justify |

Wrapping and decoration

| Class | Effect | |---|---| | no__wrap | white-space: nowrap | | anywhere__wrap | overflow-wrap: anywhere | | underline | text-decoration underline; themed color and thickness |

Opacity

| Pattern | Range | Example | Result | |---|---|---|---| | opacity__i | 0..10 | opacity__7 | opacity: 0.7 |

Colors and backgrounds

Text color utilities:

• color__primary, color__secondary, color__dark, color__light, color__danger, color__blue, color__yellow

Background utilities:

• bg__primary, bg__secondary, bg__dark, bg__light, bg__gray, bg__border, bg__danger, bg__blue, bg__yellow, bg__inherit
• bg__overlay: sets background: var(--overlay) and creates a blurred backdrop via ::after

Shadows:

• box__shadow: box-shadow: var(--shadow)

Transitions and effects

Transition duration

| Pattern | Range | Example | Result | |---|---|---|---| | transition__i | 0..512 | transition__3 | transition: 0.3s ease |

Other helpers

| Class | Effect | |---|---| | page__offset | top padding 80px | | o__fit--contain | object-fit: contain | | o__fit--cover | object-fit: cover | | debug | red 2px border |

Components

Buttons

Instead of classes, buttons and links use data attributes:

• data-ui-style

  • primary → solid background var(--primary__color)
  • secondary → solid background var(--secondary__color)
  • gray → solid background var(--gray)
  • brand__theme → dynamic radial glow on hover (uses #D3273E / #ff4d65)
  • inherit → background: inherit

• data-ui-hover-style

  • bg__bright → hover brightness(.85)
  • bg__gray → hover background var(--gray)
  • underline → hover underline with themed color and 2.5px thickness

Supporting elements:

• Optional child .nl__tool-tip fades in on hover
• Optional child .nl__radial--glow positioned by CSS variables --x/--y for brand__theme effect

Example:

<button data-ui-style="primary" data-ui-hover-style="underline" class="p__12 rounded__8 color__secondary">
  Save
  <span class="nl__tool-tip m__t--8 d__block font__sm opacity__7">Tooltip text</span>
</button>

Dropdown menu

• d__down__list: hidden by default (offset, opacity 0, pointer-events none). Add active to reveal.
• search__list: styles nested input (no border, no outline on focus-within).

<div class="p__relative">
  <button class="p__8">Menu</button>
  <div class="d__down__list p__absolute p__8 bg__primary border__8 border__secondary rounded__8">
    <input class="search__list p__8 w__max" placeholder="Search..." />
    ...
  </div>
</div>

Carousel (infinite slider)

• nl__infinite__slides (container for slides)
  • v__1 → 20% slide width, wide track; animation V1
  • v__2 → 10% slide width; animation V2
  • Modifiers: reverse__direction, pause__slider
• nl__infinite__slides__container: optional outer wrapper
• slide__message: message overlay that animates in when active

<div class="nl__infinite__slides v__1">
  <div class="slide">…</div>
</div>

Loader

• nl__spinner: apply to any element to spin continuously
• nl__loader: block with animated bar via ::after
• image__loader: placeholder effect for images; uses skeleton shimmer via ::before

<div class="nl__loader h__8 w__max bg__gray"></div>
<img class="image__loader w__256 h__256 rounded__8" />

Forms

Base element styles:

• input: themed background, border, padding, outline on focus-within; width: 100%
• textarea: same styled base; resize: none

Password helpers:

• nl__password__input__container: removes left border on inner button when focused
• nl__password__input: background primary, transparent border, rounded right corners

<div class="nl__password__input__container d__flex">
  <input type="password" class="w__max" />
  <button class="nl__password__input p__8">Show</button>
</div>

Modal

Visibility helpers:

• nl__modal--o: opacity/pointer-events wrapper; add o__visible to show
• nl__modal--c: scrollable content; add active to scale in; responsive width and rounded corners

Low-level states (already used internally):

• o__hidden / o__visible; c__hidden / c__visible

<div class="nl__modal--o p__fixed top__0 left__0 w__max h__max d__flex justify__center align__center bg__overlay o__visible">
  <section class="nl__modal--c bg__primary p__24 g__16">
    ...
  </section>
</div>

Transitions

• nl__bg--pulse--tran: one-shot background pulse via ::after and keyframes.

Theming

Light/Dark themes are applied automatically based on the user's system preference via prefers-color-scheme. Variables come from src/variables/Theme/Light.scss and Dark.scss.

You can override at runtime by setting variables on :root or a container.

:root { --primary__color: #111; --secondary__color: #fafafa; }

Examples: quick layouts

<header class="container__xl p__16 d__flex justify__between align__center">
  <a href="#" class="color__secondary font__lg underline">Brand</a>
  <nav class="d__flex g__16">
    <a href="#" class="p__8">Docs</a>
    <a href="#" class="p__8">GitHub</a>
  </nav>
</header>

<main class="container__lg g__24 p__24">
  <section class="d__grid grid__3 g__16">
    <article class="p__16 border__8 border__secondary rounded__12 box__shadow">
      <h3>Card</h3>
      <p class="opacity__7">Body text</p>
      <button data-ui-style="secondary" data-ui-hover-style="bg__bright" class="p__12 rounded__8 m__t--12 color__primary">Action</button>
    </article>
  </section>
</main>

Notes

• All numeric utilities convert px to rem at a base of 16px.
• Many utilities support a wide range i = 0..512 by default (configurable in SCSS via $utilities-max). Use sensible values; extremely large numbers are discouraged for bundle size.
• Combine utilities freely; order generally does not matter unless two utilities target the same CSS property.

Editor IntelliSense

You can enable better IntelliSense (autocomplete and hovers) for visipix.css in your editor.

• Class names in HTML/JSX:

  • VS Code: install the extension "HTML CSS Support" (ecmel.vscode-html-css) or "IntelliSense for CSS class names in HTML" (Zignd.html-css-class-completion). When you import 'visipix.css' in your project (e.g., import 'visipix.css' in your entry), the extension scans node_modules/visipix.css/dist/visipix.css and provides class name completion inside class/className attributes.
  • WebStorm/IntelliJ: enable CSS support and ensure the CSS file is part of the project (the imported node_modules CSS is indexed automatically); completion for class names will appear in HTML/JSX.

• CSS variables (custom properties):

  • VS Code can read custom properties metadata via CSS Custom Data. This package ships css-custom-data.json. Add the following to your .vscode/settings.json:

    { "css.customData": ["./node_modules/visipix.css/css-custom-data.json"] }

  • After this, you will get completion and hover info for theme variables like --primary__color, --secondary__color, --gray, etc.

Notes:

• No additional runtime is required; this only improves editor experience.
• If your workspace uses a monorepo, adjust the relative path accordingly (e.g., ../../node_modules/visipix.css/css-custom-data.json).