Widget

The Sign-In Widget (SIW) is the front door for identity verification. It empowers our customers to connect anyone, anywhere, to any technology seamlessly and safely using our embeddable experience for registration, enrollment, verification, and recovery.

Content in the SIW should focus on the end user, helping them have a smooth and seamless sign-in experience no matter where and how they use the widget.


SIW Basic

SIW customer scenarios

There are two SIW scenarios. For both, customization of the widget is extremely common.



The widget is part of an Okta-hosted sign-in page.

  • This scenario is recommended to customers.
  • The end user is redirected to an Okta page. The widget is automatically configured based on the customer’s policies.
  • Since customers can’t edit code, customization is light and includes the logo, some text strings, and colors on Okta-hosted pages. This light customization is available for all customers.



The widget is part of customers’ own applications.

  • The end user sees the widget in the application they’re using.
  • This scenario requires more manual configuration and is riskier for customers, so it’s not recommended.
  • While available to Workforce, this scenario is more likely for Customer Identity.
  • Customers may choose it to have more control over the widget’s code.
  • Since customers can edit code, they can change anything and everything—from matching the customer’s branding to all of the content.


SIW end users

The widget is where our customers and end users interact and accomplish their goals. For end users, their goal is to access an app or resource.


  • Workforce end users are employees of other companies, from global delivery services to national newspapers.
  • Customer identity end users are everybody: customers of an airline or bank, citizens engaging with government, or patients accessing their lab results.


Regardless of whether end users are employees of companies, customers, citizens, or patients, content needs to be positive, easy-to-use, and action-driven to help them reach their goals.


Writing for SIW

As the “front door,” we are introducing end users to the experience and helping them complete it quickly and easily so they can get to their resource.

Due to both its customizability and end-user audience, write SIW content so the end user doesn’t know Okta is involved.

The examples used in these guidelines are third-generation (next generation) SIW, but the content recommendations are true for all generations and versions.

Okta voice and tone

Use the Okta voice and appropriate tone to create content that is positive, easy-to-use, and action-driven. See Voice and tone

Default to positive

Use positive words and phrases to tell customers what they can or need to do instead of telling them what they can’t do or what they don’t have.

Use active voice

Active voice keeps the user in focus and shows what action they need to take more clearly.

Be concise

Think about what information the end user needs at the moment and share only that information as simply as possible. Don’t over-explain or provide extraneous information that won’t help the end user in the moment.


Use parallelism to show equal relationships

Whether in subheadings or a list of options, make the structure similar to establish consistency and help users understand the choices.


Different styles and word order creates unevenness and adds to a sense of uncertainty.

Remove unnecessary repetition

If the exact content is duplicated immediately on your component or screen, evaluate if you need both or if one of the uses is incorrect.

Use statements instead of questions

Don’t overuse questions: if every input asks a question, it increases users’ mental load and can create a sense of uncertainty, weakness, or passivity. Use a command instead.

Write in sentence case

Unless it’s the first word in a string or a proper noun, use sentence case to be as readable as possible:

  • Headlines (H1s)
  • Headings and subheadings
  • Button labels

Word choice

Use you to address the user

Using you or your in headlines and support copy helps build a relationship with the user and makes it seem that the UI is speaking directly to them.


Avoid mentioning Okta

To avoid any confusion for the end-user, don’t mention Okta in any content unless absolutely necessary.

  • Especially for an embedded scenario, customers don’t want Okta’s branding or name in their widget.


Use contractions

Use common contractions to be less formal and more conversational.


Use simple vocabulary

Avoid using jargon or technical terms that could be confusing to end-users. Use the simplest correct word to help all end users easily understand what they need to know. For example, Create is a word that kids in Grade 7 understand; Generate is a word that college students understand. So, use Create.

SIW vocabulary



  • Use when including existing information somewhere else.
  • For example, Add another security method.



  • Use instead of via.



  • Use when referring to a standalone button.
  • Always use for desktop
  • If you know the experience is mobile, use Tap instead.
  • If you need an agnostic term for both desktop and mobile, use Select.



  • Use instead of magic code or PIN.



  • Use when making up brand new information.
  • For example, Create your password.
  • Use instead of generate.


  • Use instead of Launch.



  • Follow Merriam-Webster style; not re-enter.



  • When telling an end user to choose something from a defined set of options or already existing options.
  • Never use as a synonym for Create.
  • Choose may be used as a synonym.


Set up or Setup

  • Use set up when using a verb. For example, Set up your account.
  • Use setup when using an adjective or noun. For example, Complete the setup process.


Sign in or Sign-in

  • Use sign in when using a verb. For example, Sign in to access Okta Workforce.
  • Use sign-in when using an adjective. For example, Sign-in attempt failed.
  • Don’t use either sign in or sign-in as a noun. For example, recent sign ins.
  • Don’t use sign into.


Widget

  • Capitalize as a proper noun.
  • Always include a hyphen since Sign-In is an adjective in this use.
  • Never abbreviate it as SIW for end-users.
  • In documentation, it can be referred to as the widget if introduced as Sign-In Widget on the same page.



  • Use instead of Text, Text Message.



  • Use instead of User.


Voice call

  • Use instead of Call, Phone Call.


Vocabulary to avoid



  • Remove directional prepositions to avoid responsive design and accessibility issues. These include: below, above, to the left, to the right, and under.
  • Instead see if you can use an action verb, or an InfoDev practice, like replacing below with following.
  • If you need to reference the direction of an element, start and end are much safer than anything directional. At the end of this line will remain true in LTR, RTL, and Top-Down writing systems.
  • Or, see if you can delete the direction entirely.



  • Assume everything is up to date and happens immediately unless stated otherwise.
  • Be specific if you need to mention a duration of time.
  • Avoid using vague time-based words like currently.



Use end punctuation, usually a period (.), for full sentences. In most cases, this includes:

  • Support copy
  • Inline error messages.

Don’t use end punctuation for:

  • Headlines
  • Buttons and CTAs
  • Tooltips
  • Incomplete sentences or phrases.

Exclamation point (!)

  • Don’t use exclamation points.


Quotation marks

Avoid extra characters and improve content readability by avoiding using quotation marks.

If referring to a label or instruction, use bold instead.

SIW errors

Errors in the SIW can cause frustration, or even fear, in the end users because they prevent them from achieving their goals. If the errors occur during sign up, they can create a negative experience that permanently effects end users relationship to Okta, or the company/brand they have a relationship.

So, while SIW errors follow the same patterns and best practices that apply to all error messages, they are even more important. We need to ensure we create the best end-user experience possible while experiencing an error. See Errors.

Generic error

Use this message as a last resort, usually for back-end errors that there’s no way for users to fix.


Learn more

Oktanauts can use these resources to learn more about designing the SIW:



Have questions or need support?

Oktanauts can use the following resources when building with Odyssey:

  • Check the Odyssey 1.0 FAQs.
  • Join #odyssey in Slack and tag @content to ask questions.
  • Attend Odyssey Office Hours on Mondays and Wednesdays from 1-1:30 p.m. PT / 4-4:30 p.m. ET.
  • Submit bug reports and feature requests to the Odyssey Jira board
  • Request a new component using the Odyssey component proposal.