Skip to Content
FAQ

FAQ - Frequently Asked Questions

Common questions and answers about Nostromo UI.

Installation & Setup

How do I install Nostromo UI?

npm install @jarllyng/nostromo @jarllyng/nostromo @jarllyng/nostromo

Do I need to install Tailwind CSS?

Yes, Nostromo UI is built on top of Tailwind CSS. Make sure you have it configured:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

How do I set up theming?

  1. Import the base CSS and theme:
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";
  1. Apply the theme to your HTML:
<html data-theme="nostromo" data-color-scheme="light"></html>

Components

How do I import components?

Recommended (tree-shakeable):

import { Button } from "@jarllyng/nostromo/button";
import { Input } from "@jarllyng/nostromo/input";

Also works:

import { Button, Input } from "@jarllyng/nostromo";

Can I customize component styles?

Yes! All components accept a className prop for custom styling:

<Button className="bg-red-500 hover:bg-red-600">Custom Button</Button>

How do I handle form validation?

Use with React Hook Form and Zod:

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Input, Button } from "@jarllyng/nostromo";
 
const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});
 
function MyForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm({
    resolver: zodResolver(schema),
  });
 
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Input {...register("email")} />
      {errors.email && <span>{errors.email.message}</span>}
      <Button type="submit">Submit</Button>
    </form>
  );
}

Theming

How do I create a custom theme?

Create a CSS file with your custom variables:

[data-theme="mybrand"] {
  --nostromo-color-brand-500: 220 100% 50%; /* Your brand color */
  --nostromo-color-brand-600: 220 100% 40%;
  --nostromo-font-heading: "Poppins", sans-serif;
  --nostromo-radius-md: 0.75rem;
}

Then apply it:

<html data-theme="mybrand"></html>

How do I implement dark mode?

Use the data-color-scheme attribute:

function DarkModeToggle() {
  const [isDark, setIsDark] = useState(false);
 
  useEffect(() => {
    document.documentElement.setAttribute(
      "data-color-scheme",
      isDark ? "dark" : "light",
    );
  }, [isDark]);
 
  return (
    <button onClick={() => setIsDark(!isDark)}>
      {isDark ? "Light" : "Dark"} Mode
    </button>
  );
}

Can I use my own Tailwind config?

Yes. On Tailwind v4 there is nothing to extend — the library registers its tokens through @theme, and you add your own in CSS alongside it:

@import "@jarllyng/nostromo/tailwind.css";
@import "@jarllyng/nostromo/themes/nostromo.css";
 
@theme {
  /* Your own additions, in Tailwind's namespaces */
  --color-avocado: oklch(0.84 0.18 117.33);
  --font-display: "Satoshi", sans-serif;
}

To change what the library’s own components look like, override the theme tokens rather than the Tailwind namespace:

[data-theme="nostromo"] {
  --nostromo-color-primary: 220 100% 50%;
}

Framework Support

Does it work with Next.js?

Yes! Nostromo UI is fully compatible with Next.js:

// pages/_app.tsx
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";
 
export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Does it work with Remix?

Yes! Import the CSS in your root file:

// app/root.tsx
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";

Does it work with Vite?

Yes! Just import the CSS in your main file:

// main.tsx
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";

Performance

How big is the bundle?

  • Core components: ~50KB gzipped
  • Marketing components: ~30KB gzipped
  • Themes: ~5KB gzipped
  • Total: ~85KB gzipped

How do I reduce bundle size?

Use tree-shaking by importing only what you need:

// ✅ Good - only imports Button
import { Button } from "@jarllyng/nostromo/button";
 
// ❌ Avoid - imports entire library
import * as Nostromo from "@jarllyng/nostromo";

Is it SSR compatible?

Yes! All components work with server-side rendering. No client-side dependencies.

Accessibility

Are components accessible?

Yes! All components follow WCAG 2.1 AA guidelines:

  • Keyboard navigation - Full keyboard support
  • Screen readers - Proper ARIA attributes
  • Focus management - Visible focus indicators
  • Color contrast - Meets accessibility standards

How do I test accessibility?

Use tools like axe-core:

npm install -D @axe-core/react
import { axe, toHaveNoViolations } from "jest-axe";
 
expect.extend(toHaveNoViolations);
 
test("should not have accessibility violations", async () => {
  const { container } = render(<Button>Test</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Troubleshooting

Components not styling correctly?

  1. Make sure Tailwind CSS is configured
  2. Check that you’ve imported the base CSS
  3. Verify the theme is applied to your HTML

TypeScript errors?

Make sure you have the latest version and proper imports:

import type { ButtonProps } from "@jarllyng/nostromo";

Build errors?

Check your Tailwind configuration and make sure all dependencies are installed.

License & Browser Support

What license does Nostromo UI use?

MIT License - see LICENSE  for details.

What browsers are supported?

Nostromo UI supports all modern browsers:

  • Chrome/Edge: Latest 2 versions
  • Firefox: Latest 2 versions
  • Safari: Latest 2 versions
  • Mobile browsers: iOS Safari, Chrome Mobile

Is it SSR or CSR compatible?

Both! Nostromo UI works with:

  • SSR (Server-Side Rendering): Next.js, Remix, SvelteKit
  • CSR (Client-Side Rendering): Vite, Create React App
  • Static Site Generation: Next.js, Astro

All components are SSR-compatible with no client-side dependencies.

Common Issues

What if I forget to set data-theme?

If you forget to set data-theme on your HTML element, components will use default browser styles. Always set:

<html data-theme="nostromo" data-color-scheme="light"></html>

Or in your root component:

useEffect(() => {
  document.documentElement.setAttribute("data-theme", "nostromo");
}, []);

Why aren’t my theme colors applying?

  1. Check that you’ve imported the theme CSS:
import "@jarllyng/nostromo/themes/nostromo.css";
  1. Verify data-theme is set on the HTML element
  2. Ensure Tailwind is configured with the Nostromo preset
  3. Check browser DevTools to see if CSS variables are loaded

Tree-shaking not working?

Make sure you’re using individual imports:

// ✅ Tree-shakeable
import { Button } from "@jarllyng/nostromo/button";
 
// ❌ Not tree-shakeable
import * as Nostromo from "@jarllyng/nostromo";

Support

Where can I get help?

How do I report a bug?

Create a GitHub issue with:

  • Description: Clear description of the bug
  • Steps to reproduce: How to reproduce the issue
  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Environment: Node.js version, package manager, framework
  • Code example: Minimal code example (if applicable)

How do I contribute?

See our Contributing Guide  for details.

Can I request new components?

Yes! Create a feature request on GitHub with:

  • Component description
  • Use cases
  • Design mockups (if available)
  • Implementation suggestions
Last updated on
Testing