Styling & views

Start with scoped CSS. Copy view templates into your app when you need to change the markup.

Use the included styles

The default stylesheet uses add_auth-* classes and --add_auth-* custom properties without a global reset. The gem serves its browser assets from same-origin routes, including in hosts without an asset pipeline.

Use your own classes

Point to your compiled same-origin stylesheet, then map semantic class names. For example, with Bootstrap already installed in your host:

config.stylesheet = "/stylesheets/authentication.css"
config.css_classes = {
  body: "bg-body-tertiary p-3",
  panel: "container bg-white p-4",
  field: "mb-3",
  input: "form-control",
  button: "btn btn-primary w-100",
  notice: "alert alert-danger",
  muted: "text-body-secondary",
  link: "link-primary"
}

AddAuth does not install a CSS framework. Tailwind uses the same mapping; include the initializer and any copied views in its class detection. Set config.stylesheet = nil to render without a stylesheet.

Copy the views

bin/rails generate add_auth:views --only=email_link
bin/rails generate add_auth:views --only=sessions

For the additional feature pages:

bin/rails generate add_auth:views --only=passkeys
bin/rails generate add_auth:views --only=step_up

The passkey group includes recovery. To customize the other presentation surfaces:

bin/rails generate add_auth:controllers
bin/rails generate add_auth:javascript
bin/rails generate add_auth:mailer_views

The generator preserves existing files. Customize the copied partials and relevant layout, keeping form actions, CSRF fields, cache directives and same-origin assets intact. Token pages use a minimal layout; keep analytics and third-party assets out of it.

The generator records original template versions and hashes in config/add_auth-ejections.json. Run bin/rails add_auth:doctor after a gem update to review changed upstream templates; repeated generation preserves your files. Commit that manifest with your host’s customizations.

Email appearance is optional

AddAuth includes plain-text email messages that work without a branded theme. Your app owns the wording, layout and visual identity. Use bin/rails generate add_auth:mailer_views to copy the templates when you want to change them; no theme setup is required.

Keep the intended recipient, link and purpose intact, and keep sign-in links out of logs and analytics. Verify delivery, expiry and confirmation after editing a message. Your visual design does not change the authentication contract.

Verify the new presentation

After an upgrade, doctor shows upstream changes and missing files. Review and apply changes to your host files. To accept an upstream baseline after review, remove only the reviewed entries from config/add_auth-ejections.json and rerun the relevant generator. Existing host files stay intact. Keep unreviewed entries so doctor continues to report them.

Exercise successful sign-in, validation failures, expired links and sign-out. Check narrow screens, keyboard focus and both Turbo and plain no-JavaScript navigation where allowed by policy. Keep submit controls usable in the initial HTML; provider checks must still be enforced server-side.

Follow the per-file baseline acceptance procedure after reviewing an upstream change. Re-running a generator alone does not mark an old baseline reviewed.