@justin_evo/evo-ui 1.0.1

package/src/Badge/Badge.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import styles from '../css/badge.module.scss';
+
+type BadgeSeverity = 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info';
+type BadgeVariant = 'solid' | 'outline' | 'subtle';
+type BadgeSize = 'sm' | 'md' | 'lg';
+
+interface EvoBadgeProps {
+  children: React.ReactNode;
+  severity?: BadgeSeverity;
+  variant?: BadgeVariant;
+  size?: BadgeSize;
+  dot?: boolean;
+  removable?: boolean;
+  onRemove?: () => void;
+  className?: string;
+}
+
+interface EvoBadgeGroupProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+const EvoBadgeGroup = ({ children, className = '' }: EvoBadgeGroupProps) => (
+  <div className={`${styles.badgeGroup} ${className}`}>{children}</div>
+);
+
+export const EvoBadge = ({
+  children,
+  severity = 'primary',
+  variant = 'solid',
+  size = 'md',
+  dot = false,
+  removable = false,
+  onRemove,
+  className = '',
+}: EvoBadgeProps) => (
+  <span
+    className={[styles.badge, styles[severity], styles[variant], styles[size], className]
+      .filter(Boolean)
+      .join(' ')}
+  >
+    {dot && <span className={styles.dot} />}
+    {children}
+    {removable && (
+      <button className={styles.removeBtn} onClick={onRemove} aria-label="Remove">
+        ✕
+      </button>
+    )}
+  </span>
+);
+
+EvoBadge.Group = EvoBadgeGroup;

package/src/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import styles from '../css/breadcrumb.module.scss';
+
+interface EvoBreadcrumbItemProps {
+  children: React.ReactNode;
+  href?: string;
+  current?: boolean;
+}
+
+interface EvoBreadcrumbProps {
+  children: React.ReactNode;
+  separator?: React.ReactNode;
+  className?: string;
+}
+
+const EvoBreadcrumbItem = ({ children, href, current = false }: EvoBreadcrumbItemProps) => (
+  <li className={styles.item}>
+    {href && !current ? (
+      <a href={href} className={styles.link}>
+        {children}
+      </a>
+    ) : (
+      <span
+        className={[styles.text, current ? styles.current : ''].filter(Boolean).join(' ')}
+        aria-current={current ? 'page' : undefined}
+      >
+        {children}
+      </span>
+    )}
+  </li>
+);
+
+export const EvoBreadcrumb = ({ children, separator = '/', className = '' }: EvoBreadcrumbProps) => {
+  const items = React.Children.toArray(children);
+  return (
+    <nav aria-label="breadcrumb" className={className}>
+      <ol className={styles.breadcrumb}>
+        {items.map((item, i) => (
+          <React.Fragment key={i}>
+            {item}
+            {i < items.length - 1 && (
+              <li className={styles.separator} aria-hidden="true">
+                {separator}
+              </li>
+            )}
+          </React.Fragment>
+        ))}
+      </ol>
+    </nav>
+  );
+};
+
+EvoBreadcrumb.Item = EvoBreadcrumbItem;

package/src/Button/Button.tsx

@@ -0,0 +1,125 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import styles from '../css/button.module.scss';
+
+type Variant = 'solid' | 'outline' | 'ghost' | 'soft';
+type Severity = 'primary' | 'secondary' | 'danger' | 'warning' | 'success' | 'info';
+type Size = 'sm' | 'md' | 'lg';
+type Shape = 'default' | 'rounded' | 'square';
+
+/**
+ * Configuration properties for the EvoButton component.
+ *
+ * Extends every native `<button>` attribute (type, form, name, autoFocus,
+ * aria-*, onMouseEnter, …) so consumers don't have to ask for them one by one.
+ */
+export interface EvoButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Text shown inside the button. Convenience shorthand for `children`. */
+  label?: string;
+
+  /**
+   * Visual style of the button.
+   * - `solid`   — filled background (default).
+   * - `outline` — bordered, transparent background.
+   * - `ghost`   — no border or background until hover.
+   * - `soft`    — tinted background using the severity's soft token.
+   * @default 'solid'
+   */
+  variant?: Variant;
+
+  /**
+   * Semantic color theme.
+   * @default 'primary'
+   */
+  severity?: Severity;
+
+  /** @default 'md' */
+  size?: Size;
+
+  /**
+   * Border-radius shape, orthogonal to `variant`.
+   * - `default` — normal radius.
+   * - `rounded` — pill / fully rounded edges.
+   * - `square`  — equal width/height; use for icon-only buttons.
+   * @default 'default'
+   */
+  shape?: Shape;
+
+  /** Icon rendered before the label. */
+  iconLeft?: ReactNode;
+
+  /** Icon rendered after the label. */
+  iconRight?: ReactNode;
+
+  /**
+   * When true, replaces icons with a spinner and disables interaction.
+   * `aria-busy` is set automatically.
+   */
+  loading?: boolean;
+
+  /** Optional text shown next to the spinner while `loading` is true. */
+  loadingText?: string;
+
+  /** Stretch to fill the parent's width. */
+  fullWidth?: boolean;
+}
+
+export const EvoButton = forwardRef<HTMLButtonElement, EvoButtonProps>(function EvoButton(
+  {
+    label,
+    children,
+    variant = 'solid',
+    severity = 'primary',
+    size = 'md',
+    shape = 'default',
+    iconLeft,
+    iconRight,
+    loading = false,
+    loadingText,
+    fullWidth = false,
+    disabled,
+    type = 'button',
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const content = children ?? label;
+  const visibleContent = loading ? loadingText : content;
+  const isDisabled = disabled || loading;
+
+  const classes = [
+    styles.button,
+    styles[variant],
+    styles[severity],
+    styles[size],
+    shape !== 'default' ? styles[shape] : '',
+    fullWidth ? styles.fullWidth : '',
+    !visibleContent ? styles.iconOnly : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <button
+      ref={ref}
+      type={type}
+      className={classes}
+      disabled={isDisabled}
+      aria-busy={loading || undefined}
+      {...rest}
+    >
+      {loading ? (
+        <span className={styles.spinner} aria-hidden="true" />
+      ) : (
+        iconLeft && <span className={styles.icon}>{iconLeft}</span>
+      )}
+
+      {visibleContent != null && visibleContent !== '' && (
+        <span className={styles.label}>{visibleContent}</span>
+      )}
+
+      {!loading && iconRight && <span className={styles.icon}>{iconRight}</span>}
+    </button>
+  );
+});

package/src/Card/Card.tsx

@@ -0,0 +1,257 @@
+import {
+  forwardRef,
+  createElement,
+  type AnchorHTMLAttributes,
+  type ButtonHTMLAttributes,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from 'react';
+import styles from '../css/card.module.scss';
+
+// ============================================================
+// EvoCard
+// ------------------------------------------------------------
+// Compose-based card primitive. The API takes after Radix:
+// <EvoCard.Root> is the documented surface; <EvoCard> is kept
+// as an ergonomic alias that forwards to Root.
+//
+// Visual axes are deliberately minimal — three structural
+// variants (elevated / outlined / ghost). All colour comes
+// from semantic theme tokens, so dark mode is automatic.
+//
+// When `interactive` is set the root is rendered as a real
+// <button type="button"> or, if `href` is provided, a real
+// <a>. We never use <div onClick> — keyboard users and screen
+// readers get first-class treatment.
+// ============================================================
+
+export type EvoCardVariant = 'elevated' | 'outlined' | 'ghost';
+export type EvoCardOrientation = 'vertical' | 'horizontal' | 'responsive';
+export type EvoCardHeadingLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+interface EvoCardRootBase {
+  variant?: EvoCardVariant;
+  orientation?: EvoCardOrientation;
+  children: ReactNode;
+}
+
+interface EvoCardRootStaticProps
+  extends EvoCardRootBase,
+    Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  interactive?: false;
+  href?: never;
+}
+
+interface EvoCardRootButtonProps
+  extends EvoCardRootBase,
+    Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
+  interactive: true;
+  href?: never;
+  /** @default 'button' (never auto-submits) */
+  type?: 'button' | 'submit' | 'reset';
+}
+
+interface EvoCardRootAnchorProps
+  extends EvoCardRootBase,
+    Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children' | 'href'> {
+  interactive: true;
+  href: string;
+}
+
+export type EvoCardRootProps =
+  | EvoCardRootStaticProps
+  | EvoCardRootButtonProps
+  | EvoCardRootAnchorProps;
+
+function cx(...parts: Array<string | undefined | false | null>) {
+  return parts.filter(Boolean).join(' ');
+}
+
+function rootClasses(
+  variant: EvoCardVariant,
+  orientation: EvoCardOrientation,
+  interactive: boolean,
+  className?: string,
+) {
+  return cx(
+    styles.root,
+    styles[variant],
+    styles[`orient-${orientation}`],
+    interactive && styles.interactive,
+    className,
+  );
+}
+
+export const EvoCardRoot = forwardRef<HTMLElement, EvoCardRootProps>(
+  function EvoCardRoot(props, ref) {
+    const {
+      variant = 'elevated',
+      orientation = 'vertical',
+      interactive,
+      className,
+      children,
+      ...rest
+    } = props as EvoCardRootStaticProps &
+      Partial<EvoCardRootAnchorProps> &
+      Partial<EvoCardRootButtonProps> & { interactive?: boolean };
+
+    const isInteractive = interactive === true;
+    const classes = rootClasses(variant, orientation, isInteractive, className);
+
+    if (isInteractive && typeof (rest as { href?: string }).href === 'string') {
+      const anchorRest = rest as AnchorHTMLAttributes<HTMLAnchorElement>;
+      return (
+        <a ref={ref as Ref<HTMLAnchorElement>} className={classes} {...anchorRest}>
+          {children}
+        </a>
+      );
+    }
+
+    if (isInteractive) {
+      const { type = 'button', ...buttonRest } =
+        rest as ButtonHTMLAttributes<HTMLButtonElement>;
+      return (
+        <button
+          ref={ref as Ref<HTMLButtonElement>}
+          type={type}
+          className={classes}
+          {...buttonRest}
+        >
+          {children}
+        </button>
+      );
+    }
+
+    return (
+      <div
+        ref={ref as Ref<HTMLDivElement>}
+        className={classes}
+        {...(rest as HTMLAttributes<HTMLDivElement>)}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+EvoCardRoot.displayName = 'EvoCardRoot';
+
+// ----- Section slots -----
+
+export type EvoCardHeaderProps = HTMLAttributes<HTMLDivElement>;
+export type EvoCardBodyProps = HTMLAttributes<HTMLDivElement>;
+export type EvoCardFooterProps = HTMLAttributes<HTMLDivElement>;
+
+export const EvoCardHeader = forwardRef<HTMLDivElement, EvoCardHeaderProps>(
+  function EvoCardHeader({ className, ...rest }, ref) {
+    return <div ref={ref} className={cx(styles.header, className)} {...rest} />;
+  },
+);
+EvoCardHeader.displayName = 'EvoCardHeader';
+
+export const EvoCardBody = forwardRef<HTMLDivElement, EvoCardBodyProps>(
+  function EvoCardBody({ className, ...rest }, ref) {
+    return <div ref={ref} className={cx(styles.body, className)} {...rest} />;
+  },
+);
+EvoCardBody.displayName = 'EvoCardBody';
+
+export const EvoCardFooter = forwardRef<HTMLDivElement, EvoCardFooterProps>(
+  function EvoCardFooter({ className, ...rest }, ref) {
+    return <div ref={ref} className={cx(styles.footer, className)} {...rest} />;
+  },
+);
+EvoCardFooter.displayName = 'EvoCardFooter';
+
+// ----- Title (configurable heading level) -----
+
+export interface EvoCardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
+  /** Semantic level. Visual size is fixed by the stylesheet. @default 'h3' */
+  as?: EvoCardHeadingLevel;
+  children: ReactNode;
+}
+
+export const EvoCardTitle = forwardRef<HTMLHeadingElement, EvoCardTitleProps>(
+  function EvoCardTitle({ as = 'h3', className, children, ...rest }, ref) {
+    return createElement(
+      as,
+      { ref, className: cx(styles.title, className), ...rest },
+      children,
+    );
+  },
+);
+EvoCardTitle.displayName = 'EvoCardTitle';
+
+// ----- Description -----
+
+export type EvoCardDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const EvoCardDescription = forwardRef<
+  HTMLParagraphElement,
+  EvoCardDescriptionProps
+>(function EvoCardDescription({ className, ...rest }, ref) {
+  return <p ref={ref} className={cx(styles.description, className)} {...rest} />;
+});
+EvoCardDescription.displayName = 'EvoCardDescription';
+
+// ----- Media -----
+
+export interface EvoCardMediaProps extends HTMLAttributes<HTMLDivElement> {
+  /** Convenience: renders an <img>. Omit and pass children for custom media. */
+  src?: string;
+  /** Required when `src` is set. Empty string marks the image as decorative. */
+  alt?: string;
+  /** e.g. 16/9 or '4/3'. Applied when no explicit dimensions are given. */
+  aspectRatio?: number | string;
+  children?: ReactNode;
+}
+
+export const EvoCardMedia = forwardRef<HTMLDivElement, EvoCardMediaProps>(
+  function EvoCardMedia(
+    { src, alt, aspectRatio, className, style, children, ...rest },
+    ref,
+  ) {
+    const mediaStyle: CSSProperties | undefined =
+      aspectRatio != null
+        ? { aspectRatio: aspectRatio as CSSProperties['aspectRatio'], ...style }
+        : style;
+    return (
+      <div
+        ref={ref}
+        className={cx(styles.media, className)}
+        style={mediaStyle}
+        {...rest}
+      >
+        {src ? <img src={src} alt={alt ?? ''} className={styles.mediaImg} /> : children}
+      </div>
+    );
+  },
+);
+EvoCardMedia.displayName = 'EvoCardMedia';
+
+// ----- Compound export -----
+//
+// `EvoCard` is callable (forwards to Root) AND carries the sub-components
+// as static properties so consumers can write either:
+//   <EvoCard variant="outlined">…</EvoCard>
+//   <EvoCard.Root variant="outlined">…</EvoCard.Root>
+
+type EvoCardComponent = typeof EvoCardRoot & {
+  Root: typeof EvoCardRoot;
+  Header: typeof EvoCardHeader;
+  Title: typeof EvoCardTitle;
+  Description: typeof EvoCardDescription;
+  Body: typeof EvoCardBody;
+  Footer: typeof EvoCardFooter;
+  Media: typeof EvoCardMedia;
+};
+
+export const EvoCard = EvoCardRoot as EvoCardComponent;
+EvoCard.Root = EvoCardRoot;
+EvoCard.Header = EvoCardHeader;
+EvoCard.Title = EvoCardTitle;
+EvoCard.Description = EvoCardDescription;
+EvoCard.Body = EvoCardBody;
+EvoCard.Footer = EvoCardFooter;
+EvoCard.Media = EvoCardMedia;

package/src/Checkbox/Checkbox.tsx

@@ -0,0 +1,59 @@
+import React from 'react';
+import styles from '../css/checkbox.module.scss';
+
+interface EvoCheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+  label?: string;
+  helperText?: string;
+  indeterminate?: boolean;
+}
+
+interface EvoCheckboxGroupProps {
+  children: React.ReactNode;
+  label?: string;
+  className?: string;
+}
+
+const EvoCheckboxGroup = ({ children, label, className = '' }: EvoCheckboxGroupProps) => (
+  <fieldset className={`${styles.group} ${className}`}>
+    {label && <legend className={styles.groupLabel}>{label}</legend>}
+    {children}
+  </fieldset>
+);
+
+export const EvoCheckbox = ({
+  label,
+  helperText,
+  indeterminate = false,
+  className = '',
+  disabled,
+  id,
+  ...rest
+}: EvoCheckboxProps) => {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  React.useEffect(() => {
+    if (inputRef.current) inputRef.current.indeterminate = indeterminate;
+  }, [indeterminate]);
+
+  const inputId = id ?? label?.toLowerCase().replace(/\s+/g, '-');
+
+  return (
+    <div className={[styles.checkbox, disabled ? styles.disabled : '', className].filter(Boolean).join(' ')}>
+      <input
+        type="checkbox"
+        id={inputId}
+        ref={inputRef}
+        disabled={disabled}
+        className={styles.input}
+        {...rest}
+      />
+      <label htmlFor={inputId} className={styles.label}>
+        <span className={styles.checkmark} />
+        <span className={styles.labelText}>{label}</span>
+      </label>
+      {helperText && <p className={styles.helperText}>{helperText}</p>}
+    </div>
+  );
+};
+
+EvoCheckbox.Group = EvoCheckboxGroup;