@microphi/styles 1.5.0 → 1.5.2

package/AGENTS.md

@@ -0,0 +1,10 @@
+# @microphi/styles — notes for coding agents
+
+Flex-first SCSS utility classes. Full docs: [README.md](README.md).
+
+## Rules
+
+- Load once: `@use '@microphi/styles/scss/main';` (requires `utopia-core-scss`).
+- Classes are prefixed `fx-` (`fx-flex`, `fx-gap-4`, `fx-p-2`); responsive variants use `md:` style prefixes (`md:fx-flex-row`).
+- Spacing and font sizes are fluid steps of a Utopia scale (`fx-text-{step}`), not pixel values: don't add fixed `px` overrides for them.
+- Check `scss/` for the exact class before inventing one; prefer composing utilities over new CSS.

package/README.md

@@ -1,219 +1,86 @@
-# fx-scss
+# @microphi/styles [![npm](https://img.shields.io/npm/v/@microphi/styles)](https://www.npmjs.com/package/@microphi/styles)
 
-Welcome to the **fx-scss**, a flex first set of css classes to ease
+> Flex-first SCSS utilities
 
-## Motivations
-While working on Microgamma we went through all available scss libraries. All lacked a flex first approach to layouting.
-We believe in a flex first approach when it comes to layouting. This library is the result of our though process in term of layouting and utilities.
+Utility classes (prefixed `fx-`) built flex-first: while working on [microgamma](https://github.com/microph1) none of the available libraries treated flex layout as the default, so this is ours. Spacing and font sizes are fluid, driven by a [Utopia](https://utopia.fyi) scale.
 
+## Install
 
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Folder Structure](#folder-structure)
-- [Customization](#customization)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Features
-
-- **Modular Architecture:** A well-organized structure with reusable components and utilities.
-- **Flex layout system:** Flex layout system for clear and powerful layouting.
-- **Grid layout system:** Comprehensive CSS Grid utilities for modern layout solutions.
-- **Utility Classes:** Commonly used utility classes for margin, padding, colors, typography, etc.
-# - **Mixins and Functions:** Custom mixins and functions to reduce repetitive CSS and enhance your workflow.
-# - **Theming Support:** Easy customization of themes through variables for colors, typography, and other design elements.
-- **Compatibility:** Fully compatible with modern browsers and responsive across all device sizes.
-
-## Installation
-
-Install using your favorite package manager
-
-```bash
-@microphi/flexus
+```sh
+npm i @microphi/styles utopia-core-scss
 ```
 
-Alternatively, you can manually download the SCSS files and include them in your project.
-
-## Getting Started
-
-library_name is made of the following scss modules
-
-
 ```scss
-@import 'path/to/scss-library/main.scss';
+@use '@microphi/styles/scss/main';
 ```
 
-This will include the core styles and utilities in your project. You can then start building your styles on top of the provided components.
-
-### Example Usage
+(Point Sass's load path at `node_modules`, or use the full relative path.)
 
-Here's a basic example using the flex system and utility classes:
+## Example
 
 ```html
-<div class="fx-flex fx-justify-center fx-items-center">
-  <div class="fx-w-full fx-h-50">
-    <p class="text-primary">This is a flex container</p>
-  </div>
+<div class="fx-flex fx-flex-col md:fx-flex-row fx-justify-between fx-items-center fx-gap-4">
+  <div class="fx-w-50">Half width</div>
+  <div class="fx-grow-1">The rest</div>
 </div>
 ```
 
-### Grid System
+## What's included
 
-The library also provides comprehensive CSS Grid utilities for modern layout solutions:
+| Area | Examples |
+|---|---|
+| Display | `fx-flex`, `fx-grid`, `fx-block`, `fx-hidden` |
+| Flex | `fx-flex-row`, `fx-flex-col`, `fx-flex-wrap`, `fx-grow-1`, `fx-shrink-0`, `fx-justify-between`, `fx-items-center`, `fx-fill-row` |
+| Grid | `fx-grid-cols-3`, `fx-grid-rows-2`, `fx-col-span-2`, `fx-col-start-1`, `fx-row-span-2`, `fx-place-self-center` |
+| Spacing | `fx-p-4`, `fx-px-2`, `fx-mt-1`, `fx-m-a` (auto), `fx-gap-4`, `fx-gap-row-2` |
+| Sizing | `fx-w-50`, `fx-w-full`, `fx-h-full`, `fx-vh-50`, `fx-min-w-*`, `fx-max-h-*` |
+| Position | `fx-relative`, `fx-absolute`, `fx-sticky`, `fx-inset-0`, `fx-top-0`, `fx-z-10` |
+| Typography | `fx-text-{step}`, `fx-headline-1`, `fx-title`, `fx-body-1`, `fx-caption`, `fx-uppercase`, `fx-tracking-wide`, `text-ellipsis` |
+| Misc | `fx-rounded-*`, `fx-opacity-50`, `fx-cursor-pointer` |
 
-```html
-<div class="fx-grid fx-grid-cols-3 fx-gap-4">
-  <div class="fx-col-span-2">Main content</div>
-  <div>Sidebar</div>
-  <div class="fx-col-start-1 fx-col-end-4">Full width footer</div>
-</div>
-```
-
-#### Grid Container Utilities
-
-- `fx-grid` - Sets display: grid
-- `fx-grid-cols-{n}` - Defines grid-template-columns (1-12, none, subgrid)
-- `fx-grid-rows-{n}` - Defines grid-template-rows (1-6, none, subgrid)
-- `fx-grid-flow-{dir}` - Controls grid-auto-flow (row, column, dense, etc.)
-- `fx-gap-{size}` - Sets gap between grid items
-- `fx-gap-col-{size}` - Sets column-gap
-- `fx-gap-row-{size}` - Sets row-gap
-- `fx-justify-content-{alignment}` - Justifies content along the inline axis
-- `fx-content-{alignment}` - Aligns content along the block axis
-- `fx-justify-items-{alignment}` - Justifies grid items along the inline axis
-- `fx-items-{alignment}` - Aligns grid items along the block axis
-- `fx-place-content-{position}` - Sets place-content shorthand
-- `fx-place-items-{position}` - Sets place-items shorthand
-
-#### Grid Item Utilities
-
-- `fx-col-span-{n}` - Makes item span across n columns (1-12, auto, full)
-- `fx-row-span-{n}` - Makes item span across n rows (1-6, auto, full)
-- `fx-col-start-{n}` - Sets grid-column-start property
-- `fx-col-end-{n}` - Sets grid-column-end property
-- `fx-row-start-{n}` - Sets grid-row-start property
-- `fx-row-end-{n}` - Sets grid-row-end property
-- `fx-area-{value}` - Sets grid-area property
-- `fx-place-self-{position}` - Sets place-self property
-
-#### Responsive Grid
-
-All grid utilities are responsive and support breakpoints:
+### Responsive variants
 
-```html
-<div class="fx-grid fx-grid-cols-1 sm:fx-grid-cols-2 lg:fx-grid-cols-3 fx-gap-4">
-  <div>Responsive grid item</div>
-  <div>Responsive grid item</div>
-  <div>Responsive grid item</div>
-</div>
-```
+Layout utilities have breakpoint-prefixed variants that apply from that width up:
 
-### Typography System
-
-The library provides a flexible typography system that works with the Utopia scale generator. You can customize the typography scale using the Utopia package and map the generated CSS variables to the fx-scss classes.
-
-#### Dynamic Font Size Classes
-
-The system generates font size classes dynamically based on your Utopia configuration:
+| Prefix | Min width |
+|---|---|
+| `sm:` | 640px |
+| `md:` | 768px |
+| `lg:` | 1024px |
+| `xl:` | 1280px |
+| `xxl:` | 1536px |
 
 ```html
-<!-- Generate classes from --fx-typography--6 to --fx-typography-6 based on your scale -->
-<p class="fx-text-3">Larger text using --fx-typography-3 variable</p>
-<p class="fx-text-0">Base text using --fx-typography-0 variable</p>
-<p class="fx-text--2">Smaller text using --fx-typography--2 variable</p>
+<div class="fx-grid fx-grid-cols-1 sm:fx-grid-cols-2 lg:fx-grid-cols-3 fx-gap-4">...</div>
 ```
 
-#### Semantic Typography Classes
+Breakpoints come from the `$breakpoints` map in `_variables.scss` (`!default`, so it can be overridden).
 
-The library also provides semantic classes that map to specific scale steps:
+## Spacing and typography scale
 
-```html
-<h1 class="fx-headline-1">Headline 1 using --fx-typography-1</h1>
-<h2 class="fx-headline-2">Headline 2 using --fx-typography-2</h2>
-<p class="fx-title">Title using --fx-typography-1</p>
-<p class="fx-subtitle">Subtitle using --fx-typography-0</p>
-<p class="fx-body-1">Body 1 using --fx-typography--1</p>
-<p class="fx-body-2">Body 2 using --fx-typography--2</p>
-<p class="fx-caption">Caption using --fx-typography--3</p>
-<p class="fx-overline">Overline using --fx-typography--4</p>
-```
+Spacing classes resolve to Utopia space variables (`--fx-3xs` … `--fx-2xl`), and `fx-text-{step}` to type-scale variables (`--fx-typography--4` … `--fx-typography-6`). Generate both with Utopia, using the `fx` prefix.
 
-#### Customizing Typography Variables
+Semantic typography classes map to fixed steps:
 
-To customize which CSS variables the classes use (e.g., if using a different prefix in Utopia), define a custom `$typography-vars` map before importing fx-scss:
+| Class | Step |
+|---|---|
+| `fx-headline-1` / `fx-title` | 1 |
+| `fx-headline-2` | 2 |
+| `fx-subtitle` | 0 |
+| `fx-body-1` | -1 |
+| `fx-body-2` | -2 |
+| `fx-caption` | -3 |
+| `fx-overline` | -4 |
 
-```scss
-// Define custom mapping to match your Utopia configuration
-$typography-vars: (
-  1: var(--step-typography-1),
-  2: var(--step-typography-2),
-  3: var(--step-typography-3),
-  0: var(--step-typography-0),
-  -1: var(--step-typography--1),
-  -2: var(--step-typography--2),
-  // ... etc for all steps in your scale
-) !default;
-
-// Now import fx-scss
-@import 'path/to/fx-scss/main';
-```
-
-## Folder Structure
-
-The SCSS library follows a clean, modular structure:
-
-```
-scss-library/
-│
-├── base/           # Base styles (normalize, resets, typography, etc.)
-├── components/     # Reusable components (buttons, cards, forms, etc.)
-├── layout/         # Layout helpers (grid, containers, spacing, etc.)
-├── mixins/         # Utility mixins (media queries, typography helpers, etc.)
-├── themes/         # Theming (color palettes, variables, dark/light modes)
-└── utilities/      # Utility classes (margin, padding, display, etc.)
-```
-
-### Key Files
-
-- `main.scss`: The primary file to import into your project.
-- `variables.scss`: Defines default variables for colors, typography, spacing, etc.
-- `mixins.scss`: Contains mixins to simplify responsive design, typography, and other features.
-
-## Customization
-
-The library is designed to be easily customizable. You can override the default variables by creating your own SCSS file and importing the library below your custom settings:
+If your Utopia variables use a different name, override the mapping when loading the library:
 
 ```scss
-// Custom variables
-$primary-color: #007bff;
-$secondary-color: #6c757d;
-
-// Import library after customizations
-@import 'path/to/scss-library/main.scss';
+@use '@microphi/styles/scss/main' with (
+  $typography-vars: (
+    0: var(--step-0),
+    1: var(--step-1),
+    -1: var(--step--1),
+    // ... every step in your scale
+  )
+);
 ```
-
-### Theming
-
-To create a custom theme, simply modify the variables in the `themes/` folder or define new ones in your project. You can switch between themes dynamically by overriding these variables.
-
-## Contributing
-
-We welcome contributions to improve the library! To contribute, please follow these steps:
-
-1. Fork the repository.
-2. Create a new branch for your feature or bug fix.
-3. Make your changes and ensure all SCSS is properly compiled.
-4. Submit a pull request with a detailed explanation of your changes.
-
-Please follow the [contribution guidelines](CONTRIBUTING.md) for more details.
-
-## License
-
-This SCSS library is open-source and available under the [MIT License](LICENSE).
-
----
-
-Feel free to open an issue if you have any questions or run into any issues while using the library. Happy coding!

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@microphi/styles",
-  "version": "1.5.0",
-  "description": "helper styles",
+  "version": "1.5.2",
+  "description": "Flex-first SCSS utilities",
   "scripts": {},
   "private": false,
   "repository": {
     "type": "git",
-    "url": " "
+    "url": "git+https://github.com/microph1/microphi.git",
+    "directory": "packages/styles"
   },
   "keywords": [
     "styles",
@@ -14,13 +15,25 @@
     "scss",
     "helpers"
   ],
-  "author": "cavaliere.davide@gmail.com",
-  "license": "ISC",
+  "author": {
+    "name": "Davide Cavaliere",
+    "email": "cavaliere.davide@gmail.com",
+    "url": "https://github.com/microph1"
+  },
+  "license": "MIT",
   "devDependencies": {
     "utopia-core-scss": "*"
   },
   "peerDependencies": {
     "utopia-core-scss": "^1.2.0"
   },
-  "gitHead": "12fbf2b63f2a438be307cbbacec71b93f7312fa8"
+  "homepage": "https://github.com/microph1/microphi/tree/master/packages/styles#readme",
+  "bugs": {
+    "url": "https://github.com/microph1/microphi/issues"
+  },
+  "files": [
+    "scss",
+    "AGENTS.md"
+  ],
+  "gitHead": "859e7630f4ce943bad7424ea406f87830d3c3af2"
 }

package/CHANGELOG.md

@@ -1,64 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-# [1.5.0](https://example.com/compare/@microphi/styles@1.4.0...@microphi/styles@1.5.0) (2026-08-22)
-
-### Features
-
-* **styles:** add position/layer/object utilities ([66306a2](https://example.com/commits/66306a22e64d8ee9f6586e5022197bcf7d6577f4))
-
-# [1.4.0](https://example.com/compare/@microphi/styles@1.3.1...@microphi/styles@1.4.0) (2026-07-22)
-
-### Features
-
-* **microphi:** update styles, debug, and json-db packages ([38118b2](https://example.com/commits/38118b233d2e52a701065b34a889c153107edee5))
-* **styles:** add CSS Grid utilities and documentation 🎉 ([c1b2739](https://example.com/commits/c1b2739a61df448fe52c9ba6c0deb4d7029b6924))
-* **styles:** add opacity, text-transform, letter-spacing & min/max sizing utilities; fix .fx-grid display ✨ ([0c6d75b](https://example.com/commits/0c6d75b00129236dfcc5c674f0fc57c0aeca5b0f))
-
-## [1.3.1](https://example.com/compare/@microphi/styles@1.3.0...@microphi/styles@1.3.1) (2025-10-09)
-
-**Note:** Version bump only for package @microphi/styles
-
-# [1.3.0](https://example.com/compare/@microphi/styles@1.2.5...@microphi/styles@1.3.0) (2025-09-25)
-
-### Features
-
-* **styles:** font-weight should bring !important ([9bd1fda](https://example.com/commits/9bd1fdaadf01e1e18c327c78526d156029b8aba0))
-
-## [1.2.5](https://example.com/compare/@microphi/styles@1.2.4...@microphi/styles@1.2.5) (2025-09-21)
-
-**Note:** Version bump only for package @microphi/styles
-
-## [1.2.4](https://example.com/compare/@microphi/styles@1.2.3...@microphi/styles@1.2.4) (2025-09-21)
-
-### Bug Fixes
-
-* **styles:** add more sizing options ([e944403](https://example.com/commits/e944403c47ec1d5e1f0625f6ffa638d86d191e85))
-
-## [1.2.3](https://example.com/compare/@microphi/styles@1.2.2...@microphi/styles@1.2.3) (2025-06-30)
-
-### Bug Fixes
-
-* **styles:** add more sizing options ([11c5de2](https://example.com/commits/11c5de2cd29088e3f69ed89e2c3ce1ea0fce3782))
-
-## [1.2.2](https://example.com/compare/@microphi/styles@1.2.1...@microphi/styles@1.2.2) (2025-06-29)
-
-### Bug Fixes
-
-* **styles:** adjust widths and heights so that we can always make 100 ([8ae3b5a](https://example.com/commits/8ae3b5aa4925f9a6f27b59e5537438fb2b713437))
-
-## [1.2.1](https://example.com/compare/@microphi/styles@1.2.0...@microphi/styles@1.2.1) (2024-11-15)
-
-**Note:** Version bump only for package @microphi/styles
-
-# 1.2.0 (2024-11-15)
-
-### Features
-
-* **styles:** fix deprecation warnings ([4fba924](https://example.com/commits/4fba924c5bcbfa9e4019cdfee33019e16561fbff))
-
-# [1.1.0](/compare/v0.2.10...v1.1.0) (2023-01-16)
-
-**Note:** Version bump only for package @microphi/styles