@sublimee/auth-ui

AI-first package doc for Sublime auth components.

If you are an AI agent reading the installed npm package directly, start with AI_INDEX.md.

Use This Package When

• you need a ready-to-use OAuth button,
• you want built-in structure, motion, loading, and accessibility defaults,
• you want token-driven customization instead of rebuilding button styles from scratch.

First Move

import { OAuthButton } from "@sublimee/auth-ui";

<OAuthButton provider="google" />

The package injects its runtime button styles automatically. No extra component stylesheet import or @sublimee/tokens install is required for the normal path.

If you want shared Sublime theming across your app, install @sublimee/tokens and import its CSS once:

import "@sublimee/tokens/tokens.css";

Current Public Surface

Components

• OAuthButton

Other exports

• GoogleIcon
• DiscordIcon
• useButtonAnimation

Current providers

• google
• discord

Important Defaults

• built on @base-ui/react/button
• default variant: secondary
• default interaction motion: press
• loading is built in
• default loading animation: spinner
• focus styling is semantic-token driven

Primary API

<OAuthButton
  provider="google"
  variant="secondary"
  loading={false}
  disabled={false}
>
  Continuar con Google
</OAuthButton>

| Prop | Type | Default | Meaning | |------|------|---------|---------| | provider | 'google' \| 'discord' | required | OAuth provider | | variant | 'primary' \| 'secondary' | 'secondary' | emphasis level | | animation | 'press' \| 'spring' | 'press' | interaction motion (legacy, use animationConfig) | | animationConfig | ButtonAnimationConfig | - | advanced animation control | | loading | boolean | false | shows loading UI and disables interaction | | loadingAnimation | 'spinner' | 'spinner' | loading indicator | | disabled | boolean | false | disables interaction | | className | string | - | additional CSS classes | | children | ReactNode | provider label | custom content; pass {null} for icon-only |

ButtonAnimationConfig

interface ButtonAnimationConfig {
  mode: 'press' | 'spring';
  pressDuration?: number;    // ms for press phase (spring only) - default: 150
  releaseDuration?: number;  // ms for release phase (spring only) - default: 150
  threshold?: number;        // ms to detect quick click (spring only) - default: 200
}

Animation modes:

• press (default): Button stays pressed while holding, releases immediately on mouseup with 180ms animation.
• spring: Quick clicks (<200ms) trigger a full spring animation (150ms press + 150ms release) that completes regardless of when you release. Long presses behave like standard press.

Task Routing

Google auth button

<OAuthButton provider="google" />

Primary call to action

<OAuthButton provider="google" variant="primary" />

Loading state

<OAuthButton provider="google" loading />

Spring animation

<OAuthButton
  provider="google"
  animationConfig={{ mode: 'spring' }}
/>

Extruded 3D button

Use the sublime-button--extruded class for a 3D box effect with stacked shadows:

<OAuthButton
  provider="google"
  className="sublime-button--extruded"
/>

Combine with spring animation:

<OAuthButton
  provider="google"
  className="sublime-button--extruded"
  animationConfig={{ mode: 'spring' }}
/>

Extruded button CSS custom properties:

.sublime-button--extruded {
  --sublime-button-extrude-depth: 5.5px;        /* Extrusion depth */
  --sublime-button-extrude-border-light: #E4E4E8;  /* Top/left border color */
  --sublime-button-extrude-shadow-1: #EBEBEF;   /* Shadow layer 1 (lightest) */
  --sublime-button-extrude-shadow-2: #E6E6EA;   /* Shadow layer 2 */
  --sublime-button-extrude-shadow-3: #E0E0E6;   /* Shadow layer 3 */
  --sublime-button-extrude-shadow-4: #DADAE0;   /* Shadow layer 4 */
  --sublime-button-extrude-shadow-5: #D4D4DA;   /* Shadow layer 5 */
  --sublime-button-extrude-shadow-6: #CECED4;   /* Shadow layer 6 (darkest) */
}

Customization Order

Use this order:

1. install and import @sublimee/tokens when you want shared app-wide theming
2. override semantic CSS custom properties
3. use props like variant, loading, and disabled
4. use className for visual variants like sublime-button--extruded
5. use animationConfig for interaction customization

Example:

@import "@sublimee/tokens/tokens.css";

:root {
  --sublime-color-interactive-primary: #ec4899;
  --sublime-color-interactive-primary-hover: #db2777;
  --sublime-color-focus-ring: #ec4899;
  --sublime-radius-button: 9999px;
}

Zero-Setup Contract

For this package, zero-setup means:

• the button should look like a button on first render,
• provider icon and layout should be built in,
• the consumer should not rebuild spacing, border, focus, or interaction states,
• the consumer should not need @sublimee/tokens for a usable default render,
• customization should extend the component rather than complete it.

Notes

• @sublimee/auth-ui/animations.css still exists as a legacy optional export, but the normal path should not require it.
• Public-facing default copy is currently Spanish.
• The sublime-button--extruded class provides a 3D box effect using stacked box-shadows. It adapts colors automatically for primary/secondary variants and dark mode.

License

MIT