npm package: @retronew/typography
Description: A typography styles library based on Pico CSS
Author: Retronew
Latest version: 0.4.8

# @retronew/typography

A foundational typography styles library built with SCSS, based on [Pico CSS](https://picocss.com/). Provides comprehensive typographic styles and utilities for modern web applications.

## Features

- 🎨 **Comprehensive Typography Styles** - Well-designed typography styles for headings, paragraphs, lists, blockquotes, code blocks, tables, and more
- 🌓 **Theme Support** - Built-in support for light and dark themes with automatic color scheme detection
- 🎯 **Modular Architecture** - Modular SCSS structure for easy customization and tree-shaking
- 📦 **Framework Agnostic** - Works with any framework (Vue, React, Svelte, etc.) or vanilla HTML
- 🎨 **CSS Variables** - Uses CSS custom properties for easy theming and runtime customization
- 📱 **Responsive** - Mobile-first approach with responsive typography
- ⚡ **No Build Required** - Pure SCSS, no JavaScript dependencies for the library itself

## Installation

```bash
npm install @retronew/typography
# or
pnpm add @retronew/typography
# or
yarn add @retronew/typography
```

> **Note:** This package requires `sass` as a peer dependency. Make sure you have it installed:
>
> ```bash
> npm install -D sass
> ```

## Usage

### Basic Usage

Import the main stylesheet in your SCSS file using `@use`:

```scss
@use '@retronew/typography';
```

### Available Entry Points

```scss
// Main entry - includes all typography styles
@use '@retronew/typography';

// Full Pico styles
@use '@retronew/typography/pico';

// Pico with color utilities
@use '@retronew/typography/pico.colors';

// Colors only
@use '@retronew/typography/colors';

// Access settings/variables
@use '@retronew/typography/_settings';
```

### Customizing with Variables

You can customize the library by forwarding with configuration:

```scss
@use '@retronew/typography' with (
  $semantic-root-element: 'body',
  $enable-semantic-container: true,
  $enable-responsive-typography: true // ... other custom variables
);
```

### Importing Specific Modules

For more granular control, import specific modules directly:

```scss
// Typography content only
@use '@retronew/typography/scss/content/typography';

// Code styling
@use '@retronew/typography/scss/content/code';

// Tables
@use '@retronew/typography/scss/content/table';

// Theme colors
@use '@retronew/typography/scss/themes/default';

// Helpers
@use '@retronew/typography/scss/helpers/mixin';
@use '@retronew/typography/scss/helpers/functions';
```

### In Your HTML

Simply use semantic HTML elements and the typography styles will be applied automatically:

```html
<article>
  <h1>Heading 1</h1>
  <h2>Heading 2</h2>
  <p>This is a paragraph with beautiful typography.</p>

  <ul>
    <li>List item 1</li>
    <li>List item 2</li>
  </ul>

  <blockquote>This is a blockquote with elegant styling.</blockquote>

  <pre><code>const hello = "world";</code></pre>

  <figure>
    <img src="image.jpg" alt="Example image" />
    <figcaption>Image caption</figcaption>
  </figure>

  <table>
    <thead>
      <tr>
        <th>Header 1</th>
        <th>Header 2</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Cell 1</td>
        <td>Cell 2</td>
      </tr>
    </tbody>
  </table>
</article>
```

## Requirements

- **Sass**: `>=1.23.0` (peer dependency)

## Project Structure

```
scss/
├── _index.scss              # Main entry point
├── _settings.scss           # Global settings and variables
├── pico.scss                # Full Pico bundle
├── pico.colors.scss         # Pico with colors
│
├── colors/                  # Color system
│   ├── _index.scss
│   └── utilities/
│       ├── _background-colors.scss
│       ├── _colors.scss
│       ├── _css-vars.scss
│       └── _utils.scss
│
├── content/                 # Content styles
│   ├── _code.scss
│   ├── _embedded.scss
│   ├── _figure.scss
│   ├── _link.scss
│   ├── _misc.scss
│   ├── _table.scss
│   └── _typography.scss
│
├── helpers/                 # SCSS helpers
│   ├── _functions.scss
│   └── _mixin.scss
│
├── layout/                  # Layout styles
│   └── _document.scss
│
├── themes/                  # Theme definitions
│   ├── _default.scss
│   └── default/
│       ├── _dark.scss
│       ├── _light.scss
│       ├── _schemes.scss
│       ├── _styles.scss
│       └── _theme-colors.scss
│
├── utilities/               # Utility styles
│   ├── _accessibility.scss
│   └── _reduce-motion.scss
│
└── components/              # Component styles (extensible)
```

## Theming

The library supports automatic light/dark theme switching based on user's system preference:

```scss
// The default theme automatically responds to prefers-color-scheme
@use '@retronew/typography';
```

You can also manually control the theme using CSS classes or data attributes on your root element.

## Browser Support

This library uses modern CSS features including:

- CSS Custom Properties (CSS Variables)
- `prefers-color-scheme` media query
- `prefers-reduced-motion` media query

Supports all modern browsers (Chrome, Firefox, Safari, Edge).

## Credits

This library is based on [Pico CSS](https://picocss.com/) - Minimal CSS Framework for semantic HTML.

## License

MIT

## Author

Retronew