signals.dart: Skill for Claude Code

Rules for Styling

Jaspr provides a native, type-safe CSS-in-Dart styling API via the Styles class.

1. Component-Level Styles (@css annotation)

The recommended approach for defining styles in Jaspr is inside your components to ensure better code locality.

• Rule 1: You MUST use the @css annotation on a static getter returning List<StyleRule> to scope styles to a component.
• Rule 2: You MUST use specific CSS selectors (like .main classes or #id ids) within css() to prevent your styles from bleeding into other components, as @css styles are globalized during rendering.

class App extends StatelessComponent {
  const App({super.key});

  @override
  Component build(BuildContext context) {
    return div(classes: 'main', [
      p([.text('Hello World')]),
    ]);
  }

  @css
  static List<StyleRule> get styles => [
    css('.main', [
      // Use css('&') to refer to the parent selector (.main)
      css('&').styles(
        width: 100.px, // Note: Use `.px`, `.rem`, `.percent` extensions on numbers.
        padding: .all(10.rem),
        display: .flex,
      ),
      css('&:hover').styles(
        backgroundColor: Colors.blue,
      ),
      css('p').styles(
        color: Colors.blue,
      ),
    ]),
    // Responsive queries
    css.media(MediaQuery.screen(maxWidth: 600.px), [
      css('.main').styles(flexDirection: .column),
    ])
  ];
}

2. Inline Styles

You can pass Styles instances directly to native HTML components. This renders as the style="..." HTML attribute.

• Rule 1: You MUST ONLY use inline styles for dynamic styles (e.g., styles that change based on state or parameters).
• Rule 2: For static styles, you MUST use the component-level @css annotation.
• Rule 3: You MUST NOT use inline styles for complex rules like media queries, hover states, or animations.

// Example of dynamic inline styling driven by state
class ColorBox extends StatelessComponent {
  final Color boxColor;

  const ColorBox({required this.boxColor, super.key});

  @override
  Component build(BuildContext context) {
    return div(styles: Styles(backgroundColor: boxColor), []);
  }
}