LowkeyUI Redesign Guidelines

The LowkeyUI redesign consolidates layout, component, and icon updates across builder-ui. Use this document as your starting point for future implementations regarding this redesign. Please confer with the Design & Engineering teams when in doubt.

Source of Truth

• Review the final layouts and shadcn-based design system in Figma.
• We aim for pixel-perfect designs, so treat this Figma file as the single source of truth for spacing, typography, interaction states, and responsive breakpoints.

Component Strategy

• We adopt shadcn components selectively. Simple primitives with strong native support (for example Button, Input, Textarea, Checkbox) inherit shadcn styling only. For this, you may install the shadcn component and copy its styles into app.css with its corresponding classname and make sure to prefix it with the .lowkey class, to make sure that these classes are only applied to elements/components under the lowkeyui flag.
• Complex patterns that are already well-solved by shadcn (for example DropdownMenu, Dialog, Sidebar, Sheet) are consumed directly from shadcn with minimal wrapper logic or additional custom styling.
• Ideally, when extending shadcn components, we should prefer composition over modification, in order to prevent someone from installing the component again and replacing our changes, however, we are currently not using the lucide icon library that comes built in with shadcn, therefore some changes are necessary. Please refer to shadcn files and the icons guide 👇🏻 to see how this swap is being made.

Styling Foundations

• Tailwind remains our primary utility system. All spacing, color, and typography tokens referenced in the redesign must map to Tailwind theme values configured in tailwind.config.js.
• Authors may apply Tailwind classes directly within component JSX. Avoid ad-hoc CSS whenever a Tailwind token exists.
• Align CSS variables and design tokens with the values surfaced in the Figma design system to preserve parity across platforms.

Icons

• The redesign introduces a new icon library split into two families:
  • Standard icons which currently have a fill property if exported directly from Figma.
  • Build icons which currently have a stroke property if exported directly from Figma.
• There is a dedicated script you must run in order to remove these properties and consume them. Follow the steps in https://docs.kualibuild.ninja/scripts/import-icons to see how to add and generate icons.
• Replace legacy icons with the updated assets as you touch related surfaces. This will ensure that we do not bloat the project with unused assetsb but as we phase out the current raw in favour of the new raw-lowkey icons, a strategy will probably have to be set in place to improve performance here and compile icons into a spritesheet and loading them separately.

Accessibility

• Accessibility is really important to us and our users, and we strive to achieve the highest levels of compliance possible. That means that every component / layout should take care of following accessibility best practices such as keyboard navigation, correct element roles and names for screen readers, focus order, etc. We already have some utils to help out with this, and some manual testing on top of using extensions and dev tools is always recommended but as always, check with the Design or Engineering team when in doubt.

Acceptance Criteria

• Confirm each redesigned screen matches the latest Figma layout, including responsive states.
• Verify individual components respect the shadcn usage strategy above.
• Ensure Tailwind classes are resolved through configuration without inline style overrides.
• Run a quick check on accessibility to make sure things are working as expected.