highsoft-ui

v1.0.146

Published

7 days ago

Highsoft UI

0High
0Medium
0Low

Highsoft UI

The Highsoft design system — a React component library, design tokens, a Storybook component explorer, and the Astro docs site that documents them.

Live

Design site — https://design.highdev.dev
Storybook (component explorer) — https://storybook.highdev.dev

The complete reference lives in CLAUDE.md: every component's props, the semantic token rules, and the do's & don'ts. It ships inside the published package too.

What's in this repo

| Path | What it is | Build | Ships to | | --- | --- | --- | --- | | lib/ | The component library (the published package) | npm run build → dist/ | npm — highsoft-ui | | src/ | The Astro docs site (multi-page, React islands) | npm run build:app → dist-app/ | design.highdev.dev | | stories/ | Storybook stories | npm run build-storybook | storybook.highdev.dev |

lib/ is the source of truth; the docs site and Storybook both consume it directly (via the highsoft-ui alias), so a change to a component shows up in all three.

For AI agents / LLMs

The design system is self-describing for coding agents. A prompt like "use guidelines from design.highdev.dev" should land here:

/llms.txt — concise guide: install, core rules, and a "which component when" decision matrix
/llms-full.txt — the full guide plus the complete component API
/api.json — machine-readable component API (props, types, defaults, enums)
/guidelines → redirects to /llms.txt

/llms-full.txt and /api.json are generated from lib/ source by scripts/extract-component-api.mjs (runs on predev / prebuild:app), so they can't drift from the real props. Every page also advertises /llms.txt via a <link rel="alternate"> in its <head>.

Development

npm i
npm run dev          # docs site (Astro) → http://localhost:4321
npm run storybook    # component explorer → http://localhost:6006

Both run against the live library in lib/, so editing a component hot-reloads here.

Usage

Install the package:

npm i highsoft-ui

Load the CSS — highsoft-ui/css bundles the component styles, resets and the design tokens (tokens drive the colors and dark mode):

@import 'highsoft-ui/css';

Use the components:

import { Button } from 'highsoft-ui';
// ...
<Button variant="brand" size={300}>Hello</Button>

Design tokens only

Need just the tokens — plain CSS/SCSS, WordPress blocks, no React? Install the tokens package on its own:

npm i highsoft-design-tokens

// the CSS custom properties — drives the colors and dark mode
@import 'highsoft-design-tokens/dist/css/tokens.css';

It also ships SCSS mixins, e.g. the link styles:

@use 'highsoft-design-tokens/dist/scss/mixins/links' as *;

a       { @include link; }        // subtle underline
a.fancy { @include link(fancy); } // animated slide-in underline

PHP

How to use components that need hydration (running client-side react) in PHP. This mostly applies to the wordpress block gang.

Build script

ui.tsx:

import { Header } from 'highsoft-ui';
import { render } from 'highsoft-ui/php';

render('react.php', {
  header: <Header />,
  some_other_component: <Header
    subItems={[
      {
        title: "Core",
        url: "https://www.highcharts.com/products/highcharts/",
        icon: <CoreIcon />,
      },
      {
        title: "Stock",
        url: "https://www.highcharts.com/products/stock/",
        icon: <StockIcon />,
      },
    ]}
  />
});

Run it with tsx:

npx tsx ui.tsx

PHP template

include_once 'react.php';
// ...
hsui_header();
?>

<div>
  <h2>Wordpress <3</h2>
  <?php hsui_some_other_component(); ?>
</div>

Client JS bundle

import { Header } from 'highsoft-ui';
import { hydrate } from 'highsoft-ui/php/client';

hydrate({
  header: <Header />,
  some_other_component: <Header
    subItems={[
      {
        title: "Core",
        url: "https://www.highcharts.com/products/highcharts/",
        icon: <CoreIcon />,
      },
      {
        title: "Stock",
        url: "https://www.highcharts.com/products/stock/",
        icon: <StockIcon />,
      },
    ]}
  />
});

Sub-navigation notes

Header supports a single level of secondary navigation through subItems.

Text-only items compact automatically:

<Header
  subItems={[
    { title: 'Demos', url: '/demo' },
    { title: 'Docs', url: '/docs', prefixMatch: true },
    { title: 'API', url: '/api' },
  ]}
  pathname={pathname}
/>

Icon-based items keep the taller icon layout:

<Header
  subItems={[
    {
      title: 'Demos',
      url: '/demo',
      icon: <ChartBreakoutSquare />,
      selectedIcon: <PresentationChart02 />,
    },
    {
      title: 'Docs',
      url: '/docs',
      prefixMatch: true,
      icon: <File06 />,
    },
  ]}
  pathname={pathname}
/>

Supported:

One horizontal row of secondary navigation
Optional icons and selected icons
Optional short tags next to the title
Active-state matching with pathname and prefixMatch

Not supported:

Nested submenus or flyout menus
Accordion or expand/collapse navigation behavior
Multi-line or highly custom item layouts
Perfect alignment when mixing icon and non-icon items in the same row

Formatting and linting

Prettier

Your code is formatted on save
No need to discuss style in code review. Stop all the on-going debates over styles
Saves you time and energy

Stylelint

CSS linter that helps you avoid errors and enforce conventions
Help you avoid errors, for example:
- invalid things, e.g. malformed grid areas
- valid things that are problematic, e.g. duplicate selectors
- unknown things, e.g. misspelled property names
- disallow things, e.g. specific units

stylelint-config-standard

Recommended and standard configs for stylelint.
It extends "stylelint-config-recommended" and turns on additional rules to enforce modern conventions found in the CSS specifications.

lint-staged

Allows use to run code quality tools together in a coordinated way, like prettier, eslint and stylelint.
We use ESLint. lint-staged must run ESLint before Prettier, not after.

ESLint

Find and fix problems in your JavaScript code
Many problems ESLint finds can be automatically fixed. ESLint fixes are syntax-aware so you won't experience errors introduced by traditional find-and-replace algorithms
Rules: https://eslint.org/docs/latest/rules

eslint-config-prettier

To make ESLint and Prettier play nice with each other.
Turns off all rules that are unnecessary or might conflict with Prettier.
this config only turns rules off

Husky

Automatically lint your commit messages, code, and run tests upon committing or pushing.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Highsoft UI

What's in this repo

For AI agents / LLMs

Development

Usage

Design tokens only

PHP

Sub-navigation notes

Formatting and linting

Prettier

Stylelint

stylelint-config-standard

lint-staged

ESLint

eslint-config-prettier

Husky