name	layx
description	Master reference skill for the Layx CSS-first framework — architecture, file structure, conventions, CSS patterns, JS patterns, CLI, and build system

Layx Framework — Master Reference

Layx is a CSS-first framework for building modern, high-performance landing pages. It emphasizes zero JavaScript runtime overhead for core styling while providing optional JavaScript enhancements for interactive components.

Repository: arif891/Layx

Core Philosophy

Performance First: Minimal CSS, no runtime JS dependencies for layouts
Landing Page Focused: Pre-built conversion-optimized components
CSS Layers Architecture: Uses @layer for predictable specificity
Modern CSS Features: Leverages light-dark(), CSS variables, nesting, and native functions
CSS-first: CSS handles everything it can; JS is only added when CSS alone cannot achieve the behavior

Project Structure

root/
├── layx/                    # Core framework (THE MAIN CODEBASE)
│   ├── layx.css             # Main CSS entry point — edit to add imports
│   ├── layx.js              # Main JS entry point — edit to add imports
│   ├── main/                # Core styles (always loaded)
│   │   ├── base/            # variable.css, base.css, breakpoints.css, scrollbar.css
│   │   ├── container/       # container.css
│   │   ├── layout/          # layout.css (12-column grid)
│   │   └── typography/      # typography.css
│   ├── components/          # UI components — each in own subfolder
│   ├── utilities/           # Utility classes — each category in own subfolder
│   ├── others/              # Optional modules — each in own subfolder
│   └── helpers/             # Layout helpers
│
├── src/                     # CLI tool (Node.js, ES modules)
│   ├── cli.js               # CLI entry point & command router
│   ├── commands/            # build.js, unbuild.js, optimize.js, add/
│   ├── processors/          # process.js, html.js
│   └── utils/               # cli-helper.js, build-info.js, etc.
│
├── assets/                  # User project assets (not framework)
│   ├── css/base.css         # User-wide CSS
│   ├── css/pages/           # Per-page CSS files
│   ├── js/base.js           # User-wide JS
│   └── js/pages/            # Per-page JS files
│
├── pages/                   # Additional HTML pages
├── index.html               # Main HTML entry point
├── config.mjs               # Build configuration (esbuild options)
├── layx.bat                 # Windows CLI installer
├── layx(linux).sh           # Linux CLI installer
└── layx(macOS).sh           # macOS CLI installer

CSS Architecture

Layer Order

@layer base, layout, components, others, utilities;

Layer	Purpose	Wins over
`base`	Variables, resets, typography	—
`layout`	Container, 12-column grid	base
`components`	UI components	base, layout
`others`	Optional feature CSS	base, layout, components
`utilities`	Utility class overrides	everything

Key rule: Never use !important. The layer cascade handles specificity. Utilities always win.

Key CSS Files

File	Purpose
`layx/layx.css`	Main entry — all `@import` statements go here
`main/base/variable.css`	All CSS custom properties (tokens)
`main/base/base.css`	CSS reset and base element styles
`main/base/scrollbar.css`	Custom scrollbar styles
`main/typography/typography.css`	Heading and text styles
`main/container/container.css`	`<container>` element styles
`main/layout/layout.css`	`<layout>` 12-column grid + all responsive classes

CSS Design Tokens (from `variable.css`)

:root {
    /* Typography */
    --ff-sans: 'Red Hat Display', sans-serif;
    --font-family: var(--ff-sans);
    --font-weight: 500;

    /* Spacing & Sizing */
    --base-space: .5rem;
    --base-radius: .5rem;
    --base-vpu: calc(.1vh + .1vw);  /* viewport-proportional unit */

    /* Animation */
    --base-duration: .6s;

    /* Aliases (use these in new code) */
    --space:    var(--base-space);
    --radius:   var(--base-radius);
    --vpu:      var(--base-vpu);
    --duration: var(--base-duration);

    /* Colors — automatic light/dark mode */
    --color:          light-dark(#000, #fff);
    --bg-color:       light-dark(#fff, #000);
    --heading-color:  inherit;
    --paragraph-color: inherit;
    --link-color:     light-dark(#2da5e6, #70cdff);
    --accent-color:   light-dark(#bae7ff, #2da5e6);

    /* Surface — dynamic elevation via --si (surface index) */
    --surface-color:  hsl(from var(--bg-color) h s calc(l - ...));

    color-scheme: light dark;
}

[theme=light] { color-scheme: light; }
[theme=dark]  { color-scheme: dark; }

Always use alias tokens (--space, --radius, --duration) in new code, not the --base-* originals.

CSS Conventions

/* ✅ Correct — wrapped in layer, uses tokens, light-dark() */
@layer components {
    my-element {
        padding: var(--space);
        border-radius: var(--radius);
        background: light-dark(#f5f5f5, #1a1a1a);
        transition: var(--duration);

        &.active {
            background: var(--accent-color);
        }
    }
}

/* ❌ Wrong — no layer, hardcoded values, no dark mode */
my-element {
    padding: 8px;
    background: #f5f5f5;
}

Breakpoints

/* Small (sm):  landscape phones */
@media (width >= 576px)  { }

/* Medium (md): tablets */
@media (width >= 768px)  { }

/* Large (lg):  desktops */
@media (width >= 992px)  { }

/* Ultra-wide */
@media (aspect-ratio >= 21/9) and (width >= 2000px) { }
@media (aspect-ratio >= 32/9) and (width >= 3000px) { }

Custom HTML Elements

Layx uses custom elements for semantic structure:

<container>          <!-- responsive content wrapper with padding -->
<layout>             <!-- 12-column CSS grid -->
<navbar>             <!-- navigation bar -->
<section>            <!-- page section -->

Each also works as a CSS class: <div class="layout">, <div class="navbar">, etc.

Layout System

12-column grid using <layout>:

<layout>
    <div class="x-6">Half width (6/12 cols)</div>
    <div class="x-6">Half width (6/12 cols)</div>
</layout>

<!-- Column span classes: x-1 through x-14 -->
<!-- Column start classes: xs-1 through xs-14 -->
<!-- Row span classes: y-1 through y-6 -->
<!-- Row start classes: ys-1 through ys-6 -->

<!-- Responsive variants: x-sm-6, x-md-4, x-lg-3 -->

<!-- Sub-grids -->
<layout>
    <div class="x-8 sub-x">   <!-- inherits parent columns -->
        <div class="x-4">...</div>
    </div>
</layout>

<!-- Gap classes: gap, gap-2 … gap-5, gap-x, gap-y -->
<!-- Edge layout (adds gutters): <layout class="edge"> -->
<!-- Masonry: <layout class="masonry"> -->

Components

Located in layx/components/<name>/:

Component	Has JS	Description
`accordion`	✅	Collapsible panels
`alert`	✅	Notification messages
`breadcrumb`	—	Breadcrumb navigation
`button`	—	Button styles
`card`	—	Card containers
`carousel`	✅	Image/content sliders
`chart`	✅	Data visualizations
`dialog`	✅	Modal dialogs
`draggable`	✅	Drag-and-drop
`footer`	—	Footer layouts
`form`	✅	Form elements
`media`	✅	Video/audio players
`navbar`	✅	Navigation bars
`pagination`	—	Page navigation
`popover`	—	Popup content
`section`	—	Section layouts
`sheet`	✅	Bottom/side sheets
`tab`	✅	Tab interfaces
`tooltip`	—	Hover tooltips
`window`	✅	Window-like containers

Adding a Component

See the add_component skill for full details.

Create layx/components/<name>/<name>.css — wrapped in @layer components
(Optional) Create layx/components/<name>/<name>.js — ES module
Add @import url(components/<name>/<name>.css); to layx/layx.css
Add import './components/<name>/<name>.js'; to layx/layx.js (if JS)

Utilities

Located in layx/utilities/<category>/, wrapped in @layer utilities.

Categories: border, color, display, flex, grid, height, margin, opacity, padding, position, shadow, width, z_index

See the add_utility skill for full details.

Others (Optional Modules)

Located in layx/others/<module>/. Imported manually from user JS files.

Module	Purpose
`component/`	Dynamic HTML component loader (dev-only, not production)
`theme/`	Light/dark theme toggle
`scroll_state/`	Scroll position tracking
`viewport_trigger/`	Trigger classes when elements enter viewport
`smooth_scroll/`	CSS smooth scrolling enhancement
`split_text/`	Split text into spans for animation
`mouse_tracker/`	CSS variable mouse position tracking
`partial_render/`	Partial/SPA-style page rendering
`icon/`	Icon system
`idb/`	IndexedDB wrapper
`pwa/`	Progressive Web App support
`drag_scroll/`	Drag-to-scroll for containers
`syntax_highlighter/`	Code syntax highlighting

See the add_other_module skill for adding new modules.

JavaScript Conventions

// ✅ Always ES modules
import SomeModule from '/layx/others/some/some.js';

// ✅ Target both custom element and class
const elements = document.querySelectorAll('my-element, .my-element');

// ✅ Use toggleAttribute for open/close state
element.toggleAttribute('open');

// ✅ Dispatch custom events for component communication
element.dispatchEvent(new CustomEvent('my-event', { detail: { ... } }));

// ✅ Use data-* attributes for configuration
// <div data-duration="300" data-easing="ease-out">

// ❌ Never use inline styles for theming — use CSS custom properties instead
// ❌ Never use var() in JS to set theme values — use CSS variables via el.style.setProperty()

CLI Commands

layx build           # Bundle & minify CSS/JS for production with esbuild
layx unbuild         # Restore to development state (reverse of build)
layx add -c <name>   # Add a component
layx add -t <name>   # Add a template
layx add -f <name>   # Add a font
layx optimizeImages  # Compress images with sharp

Build Process

Detects if already built → runs unbuild first (rebuild mode)
Optimizes images with sharp
Bundles CSS (assets/css/base.css + layx/layx.css) into single file
Bundles JS (assets/js/base.js + layx/layx.js) into single file
Minifies all assets/css/pages/*.css and assets/js/pages/*.js in-place
Processes HTML files
Generates build-info.json

Build config (config.mjs):

export const config = {
  build: {
    layx: {
      minify: true,
      sourcemap: false,
      format: 'esm',
      target: 'esnext',
      charset: 'utf8',
    }
  }
};

HTML Page Template

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Page Title</title>

    <link rel="stylesheet" href="/layx/layx.css">
    <link rel="stylesheet" href="/assets/css/base.css">
    <link rel="stylesheet" href="/assets/css/pages/page-name.css">

    <!-- Preload fonts -->
    <link rel="preload" href="/assets/font/Red_Hat_Display_variable.woff2" as="font" crossorigin>
  </head>
  <body>
    <!-- Content here -->

    <script src="/layx/layx.js" type="module"></script>
    <script src="/assets/js/base.js" type="module"></script>
    <script src="/assets/js/pages/page-name.js" type="module"></script>
  </body>
</html>

Testing & Development

Local dev server: localhost
Test dark mode by adding [theme="dark"] attribute to <html> or <body>
Test light mode with [theme="light"] attribute
Browser support target: modern browsers with CSS @layer support (Chrome 99+, Firefox 97+, Safari 15.4+)
light-dark() requires Chrome 123+, Firefox 120+

Important Rules Summary

Always use @layer — never write bare CSS in framework files
CSS-first — add JS only when CSS cannot achieve the behavior alone
Use design tokens — var(--space), var(--radius), var(--duration), var(--color), etc.
Dark mode via light-dark() — never handle dark mode with media queries in components
ES modules only — no CommonJS, no global scripts
No !important — rely on the layer cascade for specificity
Register imports — always add CSS to layx.css and JS to layx.js
Custom elements + class parity — always style both my-element AND .my-element selectors

layx

المزيد من هذا المستودع

المزيد من هذا المستودع

Layx Framework — Master Reference

Core Philosophy

Project Structure

CSS Architecture

Layer Order

Key CSS Files

CSS Design Tokens (from variable.css)

CSS Conventions

Breakpoints

Custom HTML Elements

Layout System

Components

Adding a Component

Utilities

Others (Optional Modules)

JavaScript Conventions

CLI Commands

Build Process

HTML Page Template

Testing & Development

Important Rules Summary

Layx Framework — Master Reference

Core Philosophy

Project Structure

CSS Architecture

Layer Order

Key CSS Files

CSS Design Tokens (from variable.css)

CSS Conventions

Breakpoints

Custom HTML Elements

Layout System

Components

Adding a Component

Utilities

Others (Optional Modules)

JavaScript Conventions

CLI Commands

Build Process

HTML Page Template

Testing & Development

Important Rules Summary

CSS Design Tokens (from `variable.css`)

CSS Design Tokens (from `variable.css`)