Stylable design system based on tailwind and react-aria.
npm install @new-black/lyraNote: 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.
- 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.
``bash`
npm i @new-black/lyra
or
`bash`
yarn add @new-black/lyra
`ts
// 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;
`
`css
/* 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;
}
}
`
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:
`bash`
cp -r node_modules/@new-black/lyra/dist/icons public
`html`
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.
`tsx
// Some root component
import { Provider } from "@new-black/lyra";
import "./index.css";
import "@new-black/lyra/dist/style.css";
export const Root = () => {
return (
);
};
`
Once installed, you can import Lyra components and styles into your project:
`javascript`
import { Button, Accordion } from "@new-black/lyra";
Check out the documentation (not yet available) for a detailed guide on using and customizing Lyra.
This package uses semantic-release for automated versioning and publishing. The release process differs based on the 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.).
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:
`bash`
npm install @new-black/lyra@next
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:
- feat: - Minor releases (0.X.0)feat: add new toast component
- Example:
- With scope:
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).
Tests are written using Playwright Test for both component and end-to-end testing. To run the tests:
`bashRun all tests
npm run test
$3
We use Playwright's snapshot testing for visual regression tests. When writing tests that check component appearance:
typescript
test("component visual test", async ({ mount }) => {
const component = await mount(
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:
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.
$3
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
$3
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:
bash
Run with UI mode
npm run test:uiRun with debug inspector
npm run test:debugRun specific test file
npx playwright test tests/components/my-component.spec.ts
``