@new-black/lyra

Lyra - Design System

Note: This package is currently under development and should not be used in a production environment.

Lyra is a comprehensive design system aimed at providing consistent and reusable components, styles, and guidelines for building user interfaces. It is designed to streamline the UI development process and ensure a cohesive visual and interactive experience across all projects.

Features

• Pre-defined UI components such as buttons, accordions, modals, etc.
• Consistent typography, colors, and spacing guidelines, we use Tailwind for that.
• Accessibility considerations implemented by default (react-aria).
• Theming capabilities to match various branding requirements.

Installation

npm i @new-black/lyra

or

yarn add @new-black/lyra

// tailwind.config.ts
import { lyraPreset } from "@new-black/lyra";

export default {
  content: [
    ...,
    "./node_modules/@new-black/lyra/dist/**/*.{js,ts,jsx,tsx,mdx}",

  ]
  presets: [lyraPreset],
  ...
} satisfies Config;

/** index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  /* Add your fonts there */
  @font-face {
    font-family: "Inter";
    src: url("/fonts/inter-regular.ttf") format("truetype");
    font-weight: 400;
  }

  /* set global styling */
  * {
    -webkit-font-smoothing: antialiased;
  }
}

Icons

For the icons used in Lyra we use an SVG sprite. To copy the SVG sprite to your public folder, execute the following command in your terminal:

cp -r node_modules/@new-black/lyra/dist/icons public

Add a link prefetch tag to prefetch the icons to your base template

<link rel="prefetch" href="/icons/icon-defs.svg" as="image" type="image/svg+xml" />

SVG sprites are a convenient way to use icons in web development. Here's why they are nice to use:

1. Reduced HTTP requests: SVG sprites allow multiple icons to be combined into a single file. This eliminates the need for separate HTTP requests for each individual icon, resulting in faster page loading times.
2. Scalability: SVG icons are vector-based, meaning they can be scaled up or down without losing quality. With an SVG sprite, you have access to a collection of scalable icons.
3. Ease of use: By using an SVG sprite, you can reference specific symbols within the sprite using their IDs. This makes it simple to insert and style icons within your HTML or CSS.
4. Efficient caching: When an SVG sprite is used, it can be cached by the browser, allowing subsequent page loads to utilize the cached sprite. This improves performance and reduces bandwidth usage.

Overall, SVG sprites offer a lightweight, flexible, and performant solution for incorporating icons into web projects.

// Some root component
import { Provider } from "@new-black/lyra";
import "./index.css";
import "@new-black/lyra/dist/style.css";

export const Root = () => {
  return (
    <Provider locale="en">
      <App />
    </Provider>
  );
};

Usage

Once installed, you can import Lyra components and styles into your project:

import { Button, Accordion } from "@new-black/lyra";

Check out the documentation (not yet available) for a detailed guide on using and customizing Lyra.

Development & Releases

This package uses semantic-release for automated versioning and publishing. The release process differs based on the branch:

Main Branch

Pushes to main trigger releases of stable versions to npm under the latest tag. These are production-ready releases following semantic versioning (e.g., 1.0.0, 1.1.0, etc.).

Develop Branch

Pushes to develop create pre-releases under the next tag on npm. These versions are suffixed with -next.X (e.g., 1.0.0-next.1). Install pre-releases using:

npm install @new-black/lyra@next

Commit Messages

We follow the Conventional Commits specification for commit messages to determine version bumps:

• fix: - Patches (0.0.X)

  • Example: fix: button hover state color
  • With scope: fix(button): hover state color

• feat: - Minor releases (0.X.0)

  • Example: feat: add new toast component
  • With scope: feat(toast): add new component

Other common types are: build, chore, ci, docs, style, refactor, perf, test

Common scopes in this project include component names (button, modal, toast), systems (theme, icons), or areas (docs, build).

Testing

Running Tests

Tests are written using Playwright Test for both component and end-to-end testing. To run the tests:

# Run all tests
npm run test

# Run tests in UI mode for debugging
npm run test:ui

# Run tests with debug inspector
npm run test:debug

Visual Regression Tests

We use Playwright's snapshot testing for visual regression tests. When writing tests that check component appearance:

test("component visual test", async ({ mount }) => {
  const component = await mount(<MyComponent />);
  await expect(component).toHaveScreenshot(); // you could add a filename inside the function
});

Updating Screenshots

When you make intentional changes to component visuals or add new visual tests, you'll need to update the snapshot references. You can force a new screenshot update for specific test files by commenting on a pull request with the following command:

/force-update-screenshot

tests/my-component.spec.ts
tests/another-component.spec.ts

Take note that you need to add a code block (three backticks) around the files to be tested.

This command will trigger the CI to update the snapshots for the specified test files.

CI/CD Integration

Tests run automatically on GitHub Actions:

• On pull request creation
• On pull request updates

The CI pipeline:

1. Runs tests in parallel
2. Generates an HTML report
3. Posts test result as PR comment
4. Uploads test artifacts for debugging failed tests

Debugging Failed Tests

When tests fail in CI:

1. Check the GitHub Actions logs
2. Download the playwright-report artifact
3. View the HTML report which includes:
   • Test execution traces
   • Screenshots at time of failure
   • Full error logs

For local debugging:

# Run with UI mode
npm run test:ui

# Run with debug inspector
npm run test:debug

# Run specific test file
npx playwright test tests/components/my-component.spec.ts