@adobe/spectrum-design-data 3.2.3 → 3.3.0-beta.1

package/guidelines/grammar-and-mechanics.json

@@ -0,0 +1,252 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/grammar-and-mechanics.json",
+  "name": "grammar-and-mechanics",
+  "title": "Grammar and mechanics",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Grammar and mechanics" },
+    {
+      "type": "guideline",
+      "content": "We use Associated Press (AP) style for in-product UX writing, with any exceptions noted on this page."
+    },
+    {
+      "type": "guideline",
+      "content": "Active voice.\n\nIn an active sentence, it's clear who's doing what. The actor is the subject, and the subject of the sentence is doing something."
+    },
+    {
+      "type": "guideline",
+      "content": "Passive voice.\n\nAt times, active voice can come across too harshly. In these cases, use passive voice. This separates the actor from the action enough to soften a sentence. In a passive sentence, action is being taken upon the subject."
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid passive voice by reframing the focus.\n\nYou can usually reframe a message to focus on the object, or on the actions someone could take, as another way to avoid passive voice."
+    },
+    {
+      "type": "guideline",
+      "content": "Common contractions.\n\nUse commonly understood contractions to keep sentences from feeling out-of-touch, robotic, or overly formal. Some common contractions: What's We'll You'll You're You've We're They're Doesn't Didn't Isn't Aren't Can't"
+    },
+    {
+      "type": "guideline",
+      "content": "Contraction considerations.\n\nAvoid contracting nouns with is, does, has, or was. This might make it look like the noun is possessive. Don’t use uncommon or old-fashioned contractions (e.g., would’ve or tweren't ). Don’t use colloquial contractions (e.g., ain't, y'all, yinz ). Be mindful of how many contractions you use in a sentence. Too many contractions can make things difficult to read. Avoid using contractions when dealing with legal concerns, payment processing, and account security. Casual isn’t always the best style when handling sensitive information."
+    },
+    {
+      "type": "guideline",
+      "content": "Why we use simple verb tenses.\n\nThere are a number of reasons why we use simple verb tenses for in-product writing: They use fewer words and are more concise. They can make content easier to scan and faster to read. Fewer words and simpler phrases mean better readability. According to the latest U.S. Census, more than 20% of people living in the U.S. speak a language other than English at home. For more people, simple verb tenses are easier to understand. Present tense improves readability scores."
+    },
+    {
+      "type": "guideline",
+      "content": "What's not simple tense.\n\nIf any of the following comes before the verb in a sentence, it’s not simple tense: Was/wasn’t, were, weren’t Has/hasn’t, have/haven’t Is/isn’t, are/aren’t Be If the verb in a sentence ends in “-ing,” it’s not simple tense."
+    },
+    {
+      "type": "guideline",
+      "content": "Sentence case.\n\nUse sentence case for all aspects of designing or re-designing Adobe product experiences, including titles and UI elements (e.g., tooltips, tabs, menu items). This transition will take time for older products, and temporary inconsistency is fine. Writing in sentence case has been proven to be easier for users to read and comprehend, it sounds more friendly and less formal, and it helps better identify proper nouns and branded terms that need to be capitalized. When to use sentence case: Only capitalize the first word in a phrase, title, or UI reference (e.g., Adjust borders tool) Always capitalize proper nouns and branded terms (e.g., Adobe Help Center) Capitalize acronyms (e.g., XD, AEM)"
+    },
+    {
+      "type": "guideline",
+      "content": "Title case.\n\nUse title case only when it clarifies that we’re speaking about a specific, official entity (such as a title or name). Title case is often a marker of formality in English, and overuse can cause users stress by implying formality or officialness where it doesn’t exist."
+    },
+    {
+      "type": "guideline",
+      "content": "All caps.\n\nUse all caps sparingly. When to use all caps: Acronyms, such as accepted product names on second attribution (e.g., Adobe Experience Manager (AEM)) Names of file extensions (e.g., TIF, ZIP, or PSD files) All caps should never be used to emphasize a point."
+    },
+    {
+      "type": "guideline",
+      "content": "Branded terms.\n\nUse title case to reference branded terms, such as names and features. This includes the names of Adobe products, like Adobe Photoshop or Advertising Cloud. Here are some common branded terms: Creative Cloud Photoshop Lightroom Illustrator Premiere Pro XD Adobe Stock Document Cloud Fill & Sign Magic Heal Adobe Sensei Experience Cloud Advertising Cloud Analytics Audience Manager Campaign Experience Manager Commerce Cloud Marketo Engage Adobe Acrobat Adobe Sign"
+    },
+    {
+      "type": "guideline",
+      "content": "Referring to the user.\n\nIn UX content, we want to talk about what’s happening rather than who or what is making something happen. We avoid speaking as our users. In nearly all situations, we aim to be conversational and talk to the user — not as them. Any exceptions depend on situational needs for sensitivity and clarity."
+    },
+    {
+      "type": "guideline",
+      "content": "Second person.\n\nMost of the time, use second person ( you, your, you’re ) to address users and services."
+    },
+    {
+      "type": "guideline",
+      "content": "First person.\n\nUse first person ( me, I, my ) only in these situations: Someone responds to the interface or answers a question they've been asked directly When additional sensitivity is necessary, or to indicate privacy When there's a legal need to use first person to ask for consent (e.g., “I agree to these terms and conditions”) On rare occasions, it can be appropriate to use we or us to mean “Adobe”: \"We're sorry\" (for a critical error) \"Help us improve this feature\" (requesting feedback)"
+    },
+    {
+      "type": "guideline",
+      "content": "Singular they.\n\nIn most situations, Adobe doesn't need to know or assume the gender of our users. So when we refer to users, we use singular they. We don’t use “he/she” or “(s)he” — those are clunky and they exclude users who identify outside of the male/female binary. Use any of these variants of they in their proper grammatical contexts: They Them Their Theirs Themselves Themself"
+    },
+    {
+      "type": "guideline",
+      "content": "Ampersand.\n\nDon’t use ampersands (&) in UI copy. Instead, spell out the word “and.” Using the word “and” is more inclusive, localizable, and readable: It’s more widely known and understood for people who are non-fluent English speakers It translates more easily into many languages Spelled-out words require less mental and cognitive effort to read Ampersands bring attention to the conjunction in a phrase which is the least important part of the sentence The ampersand symbol can be distracting, since it’s taller than many letters and is an unusual shape"
+    },
+    {
+      "type": "guideline",
+      "content": "Apostrophe.\n\nDon’t use apostrophes (') in place of quotation marks. When pluralizing singular and plural words, add apostrophe-\"s\" when there’s no \"s\" at the end. For plural nouns that end with \"s,\" add only an apostrophe. For any other specifics on possessive apostrophes, refer to the AP style handbook."
+    },
+    {
+      "type": "guideline",
+      "content": "Asterisk.\n\nUse asterisks ( * ) or \"(required)\" to establish form fields as required. Don’t use asterisks to denote anything as optional. Make sure to use the Spectrum asterisk icon that comes built in with the design components — not the text form of an asterisk within the label string. Don’t use asterisks in running text or labels when parentheses or a tooltip would suffice."
+    },
+    {
+      "type": "guideline",
+      "content": "At sign.\n\nDon’t use the at sign (@) in place of the word \"at."
+    },
+    {
+      "type": "guideline",
+      "content": "Brackets.\n\nDon’t use brackets ([] {}) in UI copy or running sentences. Instead, use parentheses ( ( ) )."
+    },
+    {
+      "type": "guideline",
+      "content": "Colon.\n\nTry to simplify a complex sentence into multiple sentences first, but if you can’t, try a colon (:). Colons are helpful when introducing lists of items or steps in a workflow. The lists and steps should be introduced on new lines. They’re also useful for high-level headlines or marketing-sounding UI content. Don’t use a colon at the end of a label for a form field. The design component should already communicate the relationship between the label and the input."
+    },
+    {
+      "type": "guideline",
+      "content": "Comma.\n\nWhen listing things, use the serial comma (also known as the Oxford comma). This means providing a comma before the word “and” when listing multiple items in a sentence. If you’re having to use a lot of commas in a sentence, consider whether you can split the sentence up with periods or em dashes."
+    },
+    {
+      "type": "guideline",
+      "content": "Ellipsis.\n\nUse ellipses (…) when truncating text in small spaces. Use an ellipsis at the end of the text to communicate the progress of something that is in process, such as a waiting or loading state. In general, avoid using an ellipsis in a button. If a button will take a user to a completely different or more complicated view (such as going from a dialog to a settings panel), it can be acceptable to include an ellipsis at the end of the label text to communicate that there's more action needed beyond the button's initial interaction. For prompt text in a picker, use an ellipsis at the end of the text to communicate that a user can select an option (e.g., “Select category…”). If your product uses a menu pattern native to an operating system (OS), follow the company’s guidelines. If it uses Spectrum’s Menu component, see Ellipses in menu commands. If you need to directly refer to a UI element whose name ends with an ellipsis (e.g., “ Find… “) in running text, drop the ellipsis: “Use Find to search the database.” Use the more icon (not an ellipsis as a string of text) when designing a More menu."
+    },
+    {
+      "type": "guideline",
+      "content": "Emoji.\n\nDon’t use emoji in any interface language. Emoji often convey tones that may be inappropriate in certain contexts. They’re also difficult to localize, and tend to diminish readability and comprehension. When writing about emoji, you can have one emoji or multiple emoji. The spelling is the same for both the singular and plural noun forms."
+    },
+    {
+      "type": "guideline",
+      "content": "Equals sign.\n\nDon’t use an equals sign (=) in place of the word \"equals,\" and don’t use this as shorthand for \"meaning,\" \"means,” or \"is."
+    },
+    {
+      "type": "guideline",
+      "content": "Exclamation mark.\n\nDon’t use exclamation marks (!) since they are difficult to localize and easy to overuse."
+    },
+    {
+      "type": "guideline",
+      "content": "Greater than and less than.\n\nWhen communicating navigation, such as in breadcrumbs, use the \"chevron\" icon built into the component, not the greater than symbol. Don’t use the greater than and less than symbols to communicate steps in a flow — use bulleted or numbered lists instead. Don’t use these symbols to replace the words \"greater than\" or \"less than.\" And don’t use them to accent or decorate a word."
+    },
+    {
+      "type": "guideline",
+      "content": "Hyphen and dash.\n\nUse em dashes (—) to separate distinct but related thoughts. Include spaces before and after the em dash. Use en dashes (–) for number ranges and lengths of time, with no spaces before or after the en dash. Don’t use them when paired with the words “from” or “between.” When needing to show gaps in data in a table, use an en dash to represent null, unavailable, or inapplicable values. Use hyphens (-) between words, and with no spaces before or after the hyphen."
+    },
+    {
+      "type": "guideline",
+      "content": "Minus sign.\n\nDon’t use the minus sign (-) in place of the word “minus,” “without,” “less,” “negative,” or other words related to subtraction."
+    },
+    {
+      "type": "guideline",
+      "content": "Parentheses.\n\nUse parentheses ( ( ) ) to provide supplementary context. Don’t use parentheses in simple tooltips. In rich tooltips, they can indicate keyboard shortcuts. Don’t use brackets in place of parentheses."
+    },
+    {
+      "type": "guideline",
+      "content": "Period.\n\nIn general, if your text is a full sentence, add a period to the end. If it's a short, direct phrase — either standalone, or within a UI component like a toast or alert banner — don't add a period. In the majority of cases, don’t use periods (.) or any other punctuation on the end of bulleted or numbered lists. If one list item is a complete sentence, then it would end with a period (or question mark). In this case, use periods at the end of all items. Don’t use periods in headers or buttons."
+    },
+    {
+      "type": "guideline",
+      "content": "Plus sign.\n\nDon’t use plus signs (+) in place of the word \"and,\" bullet points, or as any other design elements. Don’t use plus signs when indicating there is more of something available."
+    },
+    {
+      "type": "guideline",
+      "content": "Question mark.\n\nWhen writing titles, questions marks (?) are the only acceptable punctuation mark to include. Avoid using question marks to ask rhetorical questions."
+    },
+    {
+      "type": "guideline",
+      "content": "Quotation mark.\n\nIn UI copy, only use quotation marks (“”) when quoting someone’s words or when referring to a file or asset name. Always use smart quotation marks (also called “curly” or “directional”), except when showing code. Smart quotation marks are easier to read because they better match the other characters in a typeface. Straight quotes may also be confused with prime symbols, which are used for measurements. Don’t use quotation marks when directly referring to interface elements. View the Typography page for guidance on using bold text to do so."
+    },
+    {
+      "type": "guideline",
+      "content": "Semicolon.\n\nDon’t use semicolons (;). If you need a break in a sentence, use periods, commas, or occasionally em dashes. While semicolons are useful for connecting two related thoughts, they add a formal and academic tone to text and have shown to negatively affect user comprehension in UX writing."
+    },
+    {
+      "type": "guideline",
+      "content": "Slash.\n\nDon’t use backward slashes, and don’t use a forward slash ( / ) to combine words or ideas. This comes across as noncommittal, and affects comprehension and clarity. Instead, use the words “and” or “or.” Don’t use “and/or.”"
+    },
+    {
+      "type": "guideline",
+      "content": "Vertical bar.\n\nDon’t use the vertical bar (|) in running text. Avoid using it to divide information in places other than webpage titles tags and footer info. It shouldn’t be used for purely stylistic or decorative purposes when blank space between items is sufficient. When you use the vertical bar, use an icon and not its text form. Additionally, make sure you change its name in JAWS to “Pause” for proper accessibility."
+    },
+    {
+      "type": "guideline",
+      "content": "Amounts.\n\nUse K for thousands, M for millions, B for billions, capitalized, no periods. Include a space between the number and the unit of measurement (e.g., \"71 M records found\")."
+    },
+    {
+      "type": "guideline",
+      "content": "Measurements and dimensions.\n\nFor full sentences where measurements or other numbers are present, use AP style and spell out the unit of measurement (e.g., 2 points, 2 picas, 2 pixels, 2 megabytes). Similarly, use AP style when abbreviating measurements or time. Make sure there’s a space between the number and the unit of measurement (e.g., 2 pt, 2 MB, 2 min, 2 hr)."
+    },
+    {
+      "type": "guideline",
+      "content": "Months.\n\nUse Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec (no periods)."
+    },
+    {
+      "type": "guideline",
+      "content": "Days.\n\nUse Sun, Mon, Tue, Wed, Thu, Fri, Sat (no periods)."
+    },
+    {
+      "type": "guideline",
+      "content": "Time.\n\nUse sec, min, hr as singular, no periods, no comma, and with a space in between the number and the unit of time (e.g., 1 hr 21 min). Use lowercase am and pm indicators without a preceding space, unless you’re describing 24-hour time (e.g., 17:15)."
+    },
+    {
+      "type": "guideline",
+      "content": "Currency.\n\nUse the numerical form of $1.00 when formality is needed, or when the number is dynamic and might include cents. Use the number form of $1 when you need a more casual, neutral tone or if there is a space constraint and you can round off to the nearest dollar. Use the international abbreviation for the currency when you need to disambiguate types of currency (e.g., \"$100 USD equals $138.21 SGD\")."
+    },
+    {
+      "type": "guideline",
+      "content": "Large numbers.\n\nUse a comma to offset groups of three digits, for readability: 10 100 1,000 10,000 100,000 1,000,000 But for the best readability, when citing large, round numbers, spell out the word: 4 thousand 81 million 2.5 billion"
+    },
+    {
+      "type": "guideline",
+      "content": "Numerals.\n\nIn running text, write out the words zero through nine, then start using the number for 10 and higher. When telling time, presenting a series or range, or providing a timestamp, use the number forms: 0 through 9. You can adjust how you format numerals if you feel it’s appropriate for your situation. Using a number adds more emphasis than spelling out the word. For example, if you were to say “Compare two files and see the changes,” the emphasis is on the comparison, not on the number of files. \"Read all eight comments\" focuses on the availability of comments; \"Read all 8 comments\" focuses on the number of comments. If you’re mentioning currency or time alongside other types of numbers, spell out the number to make the currency or time more prominent."
+    },
+    {
+      "type": "guideline",
+      "content": "Percentages.\n\nUse the percent symbol (%) instead of spelling out the word \"percent."
+    },
+    {
+      "type": "guideline",
+      "content": "Dates.\n\nDate formatting is contextual, and it will depend on your product and use case. Different kinds of date formatting can be used for standalone strings in running text or for strings in more data-rich views. Some experiences might require the full format, where others might require something more compact: Full: Monday, August 21, 2017 at 3:07pm Compact: Mon, Aug 21, 2017, 3:07pm Additionally, dates are often localized. For example, in Europe and the U.K., the previous date example would be written: Full: Monday, 21 August at 15:07 Compact: Mon, 21 Aug, 15:07 For U.S. English, you can also format dates as MM-DD-YYYY, using the numeral for the month instead of the word. Use a 2-digit format (including a 0, even with single digit months and days). The 2-digit format also helps make it easier to parse and compare multiple dates, especially in tables or lists: 02/24/2000 04/01/2015 Work with a localization expert to localize dates and times for your product’s specific cases. Learn more about the formatting for abbreviating dates (months and days) in the Abbreviations section."
+    },
+    {
+      "type": "guideline",
+      "content": "Time.\n\nDo not use:00 with whole numbers When presenting a range of time, use an en dash without spaces in between, and do not include am or pm on the first time if it’s the same as the last When translating to 24-hour time, do not include am and pm (e.g., 17:15) Learn more about the formatting for abbreviating time (hours, minutes, seconds, and am and pm indicators) in the Abbreviations section."
+    },
+    {
+      "type": "guideline",
+      "content": "Relative time is either used to convey the amount of time elapsed since an event (such as how long since a project was last saved or edited), or the amount of time remaining in an ongoing process (such as how much longer an asset will take to render or download). Use words like “hour,” “day,” and “month” and their respective abbreviations once the time has reached that threshold for measurement. Such as: 1 hour (rather than 60 minutes) 1 day (rather than 24 hours) 1 month (rather than 30 days) 1 year (rather than 365 days) The usage of relative time is contextual, and will depend on your product and use case (for example, timestamps and locale style or standards). If you’re not building in U.S. English, partner with a localization expert for your product’s specific considerations."
+    },
+    {
+      "type": "guideline",
+      "content": "Elapsed time.\n\nWhen describing elapsed time, break it down as follows: Just now 1 minute ago X minutes ago 1 hour ago X hours ago 1 day ago X days ago 1 month ago X months ago 1 year ago X years ago"
+    },
+    {
+      "type": "guideline",
+      "content": "Remaining time.\n\nWhen showing remaining time, use the following pattern: X hours remaining X minutes remaining X seconds remaining For describing an estimated or uncertain amount of remaining time, use the word \"about\" at the beginning of the string."
+    },
+    {
+      "type": "guideline",
+      "content": "Timestamps.\n\nFor a timestamp in a video editor where precision is needed, go by hour, then minute, then second, following this formula: HHSS. In a tutorial playlist, for example, less detail is needed. If the video is less than an hour long, omit the hours."
+    },
+    {
+      "type": "guideline",
+      "content": "Time zones.\n\nAvoid time zones unless absolutely necessary — if possible, dynamically convert to the user’s time zone. If the time zone is absolute, use the common name, like Pacific Time, or India Standard Time. Don’t use UTC formulas. If space is constrained, use a time zone's acronym (e.g., PST, EST), but make sure you provide extra context to your localization team if doing so. For relative time and clarity, say “in your time zone.”"
+    },
+    {
+      "type": "guideline",
+      "content": "Introductory phrases.\n\nUse an introductory phrase with a colon to lead into the list, and write each list item so it works with that phrase."
+    },
+    {
+      "type": "guideline",
+      "content": "Be consistent and use parallel construction.\n\nPhrase your list items to be consistent with each other as much as possible. This helps with comprehension and readability. Some things to keep in mind when writing lists: Capitalize the first letter of each list item. Generally, don’t use terminal punctuation in list items, unless it’s a complete sentence or sentences. If the list includes action items (as in a series of instructions), the entire list should follow the same format, with the verb first. If it’s a list of nouns, all items on the list should include nouns."
+    },
+    {
+      "type": "guideline",
+      "content": "Capitalize each list item.\n\nCapitalize the first letter of each list item and use sentence case."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/grammar-and-mechanics",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "UX writing",
+    "AP style",
+    "Active voice",
+    "Passive voice",
+    "Contractions",
+    "Contraction considerations",
+    "Verb tenses",
+    "Readability",
+    "Localization"
+  ]
+}

package/guidelines/grays.json

@@ -5,62 +5,35 @@
   "title": "Grays",
   "category": "designing",
   "documentBlocks": [
-    {
-      "type": "purpose",
-      "content": "Adding an extra shade in the low range allowed for us to make more incremental steps between background grays.\n\nThis update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100.\n\nField borders are currently the only objects that stay gray-300 in the default state."
-    },
-    {
-      "type": "guideline",
-      "content": "Gray-100 was previously the default background color. With Spectrum 2, gray-25 is the new default background color, which makes the UI brighter and have higher contrast than before."
-    },
-    {
-      "type": "guideline",
-      "content": "Spectrum 2 includes two new grays — gray-25 and gray-1000 — plus an update to the rest of the 11 grays. This means that there are 13 grays total in the system."
-    },
-    {
-      "type": "guideline",
-      "content": "The Spectrum team collected feedback from product teams across Adobe and determined that the 6.0.0 color system for light UI had an issue with the steps between gray-50 and gray-75. The difference between these two was so slight it was almost imperceivable, making it so that gray-75 was not very useful. Also, the grays from -100 to -400 had too much contrast between each step, making it so that each component state appeared too harsh. Gray-900 was solid black, which was too high of a contrast to be used in text components. Reading solid black text on a solid white background is not ideal; it creates optical strain for a significant number of users."
-    },
-    {
-      "type": "guideline",
-      "content": "Adding two new grays also allowed us to keep a solid black (in light UI) and solid white (in dark UI) without having to keep gray-900 so bright. Now gray-1000 can be used for borders with opacities."
-    },
-    {
-      "type": "guideline",
-      "content": "Adding an extra shade in the low range allowed for us to make more incremental steps between background grays."
-    },
-    {
-      "type": "guideline",
-      "content": "With the 6.0.0 gray system, users working in apps that support dark theme felt the colors were too light and muddy. And, users working in apps that support darkest theme felt the UI was too high-contrast, which makes it difficult to view the screen comfortably for long periods of time. The Spectrum 2 update addresses both issues by combining the dark and darkest themes into a new theme, with brightness values that are between the two existing themes."
-    },
-    {
-      "type": "guideline",
-      "content": "This update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100."
-    },
-    {
-      "type": "guideline",
-      "content": "There are no current WCAG or W3C guidelines about if every fill and stroke in every component of every state needs to be 3:1 in contrast. Another thing to consider is that it’s irresponsible to approach the topic of contrast with a “one-size-fits-all” approach: every user has different needs, and design should account for user preference and customization. While one user may need interfaces to be higher contrast to be able to more clearly read and interact with the content, others may prefer interfaces to be lower in contrast (for example, people who are prone to getting migraines)."
-    },
+    { "type": "purpose", "content": "Grays" },
     {
       "type": "guideline",
-      "content": "Because of this, Spectrum designs all active states of UI components to be at least 3:1 in contrast in some way with the background (such as a text field’s active state border). And, all objects within components, such as icons, drag handles, and text, are also compliant with the 3:1 or 4.5:1 requirement. Other graphical objects also always use at least 3:1 contrast and are accompanied by textual descriptions. Products using Spectrum should be built in such a way that the interface contrast, coloring, sizing, motion, and more can all be adjustable by the user to fit their own specific needs."
+      "content": "Gray-25, -50, and -75 are reserved for background layers. Gray-100, -200, and -300 are used for lower contrast component background progressions or borders. Gray-800 and -900 are used for higher contrast component backgrounds such as text and active borders. This ensures that components are always visible, regardless of the background color."
     },
     {
       "type": "guideline",
-      "content": "The Spectrum 2 color update changed gray-900 (which is used by most heading or title text) to slightly lower contrast in both dark and light UI to ensure improved readability for as many users as possible."
+      "content": "In Spectrum, gray-25 is the default background color, which makes the UI bright and higher contrast."
     },
     {
       "type": "guideline",
-      "content": "Color updates are breaking changes, so you’ll need to use the following information to responsibly migrate to Spectrum 2 colors. If this isn’t done correctly, backgrounds and components will appear extra dark."
+      "content": "Spectrum utilizes a simplified color theming system with a single dark mode. Spectrum’s dark theme is utilized for both the dark color theme (in light device mode) and for dark device mode."
     },
     {
       "type": "guideline",
-      "content": "Field borders are currently the only objects that stay gray-300 in the default state."
+      "content": "Adobe aims to be AA compliant for WCAG guidelines. The latest 2.2 guidelines require that text is at least 4.5:1 in contrast for small text. Spectrum never deviates from this. The World Wide Web Consortium (W3C) also requires active, non-text components to have a minimum of 3:1 in contrast against adjacent colors. Some elements are exempt from this (like disabled items, decorative items, user-set items, or logotypes). This relates to both UI components such as text fields and buttons, and to graphical objects like icons or illustrations. There are no current WCAG or W3C guidelines about if every fill and stroke in every component of every state needs to be 3:1 in contrast. Another thing to consider is that it’s irresponsible to approach the topic of contrast with a “one-size-fits-all” approach: every user has different needs, and design should account for user preference and customization. While one user may need interfaces to be higher contrast to be able to more clearly read and interact with the content, others may prefer interfaces to be lower in contrast (for example, people who are prone to getting migraines). Because of this, Spectrum designs all active states of UI components to be at least 3:1 in contrast in some way with the background (such as a text field’s active state border). And, all objects within components, such as icons, drag handles, and text, are also compliant with the 3:1 or 4.5:1 requirement. Other graphical objects also always use at least 3:1 contrast and are accompanied by textual descriptions. Products using Spectrum should be built in such a way that the interface contrast, coloring, sizing, motion, and more can all be adjustable by the user to fit their own specific needs. View the Inclusive design page for more information about accessibility and inclusivity in the design system."
     }
   ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/grays/",
-  "lastUpdated": "2026-02-02",
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/color/grays",
+  "lastUpdated": "2026-08-07",
   "status": "published",
-  "tags": ["designing"],
-  "related": [{ "ref": "attention-hierarchy" }, { "ref": "colors" }]
+  "tags": [
+    "gray-system",
+    "neutral-grays",
+    "Gray-25",
+    "Gray-50",
+    "Gray-75",
+    "Gray-100",
+    "Gray-800",
+    "accessibility"
+  ]
 }

package/guidelines/header-browsing-context.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/header-browsing-context.json",
+  "name": "header-browsing-context",
+  "title": "Browsing context: Header",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Browsing context: Header" },
+    {
+      "type": "guideline",
+      "content": "Limit the number of call-to-action (CTA) buttons.\n\nAs a general rule, only use one call-to-action (CTA) button, aside from any buttons used to log in or log out, as defined in the universal nav. When too many CTAs are shown at once, the messages compete for attention and dilute the ability for a focused attention hierarchy. If there are multiple actions, consider combining them into a single menu or use other button types. The button should represent the most important CTA across the product; for example, “Share” and “Get desktop app” are common CTAs."
+    },
+    { "type": "guideline", "content": "Examples" },
+    {
+      "type": "guideline",
+      "content": "Keyboard interactions.\n\nIf a “skip to main content” button is enabled, it appears only on keyboard focus as the first item in the focus order. View details and examples of keyboard interactions documentation. Key Interactions TabFocuses onto or off of the header.Arrow keysMoves between header navigation items.Space/enterExecutes selection of the item and changes the view of the page in the content area. The focus remains on the selected header item."
+    },
+    {
+      "type": "guideline",
+      "content": "Cursor guidelines.\n\nState Cursor Description HoverPointer Product icon and name is a link and should use a pointer.HoverArrowEverything else that is not a link."
+    },
+    {
+      "type": "guideline",
+      "content": "Diagram with notes about the app frame header in the editing context. If there’s a menu represented by a hamburger icon, such as the application menu in Creative Cloud, it should be shown to the left of the product logo for continuity with the browsing context. The product name can be hidden in the editing context in order to provide more room for other actions. The height of the header should be the same as in the browsing context (56 px)."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/app-frame/header-browsing-context",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "App frame header",
+    "Top App Bar (TAB)",
+    "Product lock-up",
+    "Navigation",
+    "Universal nav"
+  ]
+}

package/guidelines/icon-fundamentals.json

@@ -5,10 +5,7 @@
   "title": "Icon fundamentals",
   "category": "designing",
   "documentBlocks": [
-    {
-      "type": "purpose",
-      "content": "### Icons designed to balance personality with function\n\nSpectrum 2 icons are crisp, modern, and clean. They have more personality in the form of rounder corners and motion, and use more playful but modern metaphors when there's the need to have more brand expression (for example, in feature onboarding, marketing, and Learn content). The updated icon style picks up the clean and irreducible style of Spectrum and supports the efforts to bring a unified experience to all Adobe products.\n\n### What's been updated?\n\nMost noticeably, there's been a switch to an outline style from the previous style of icons as being filled. There's also an updated priority for using meaningful metaphors consistently, focusing on content, and helping users navigate across interfaces. This combines into a cohesive theme: **icons signal familiarity**. In a product portfolio as complex as Adobe's, this familiarity is expressed through a consistent and cohesive usage of UI elements, colors, patterns, and icon metaphors.\n\nThe purpose of the updated icon style isn't just about functionality or the Adobe brand: it's about how many intricate details add up to make a big difference in the user experience. Using icon metaphors consistently makes Adobe's products usable."
-    },
+    { "type": "purpose", "content": "Icon fundamentals" },
     {
       "type": "guideline",
       "content": "How the Spectrum 2 icon set was developed.\n\nSeveral teams collaborated on the overall Spectrum 2 design language updates. One goal for iconography was to build out the current style into a unified icon language, to more closely align with our multi-platform design approach and to look and feel cohesive with the iOS and Android iconography systems. Previous testing and the launch of the outline icon style for Acrobat Modern Viewer and Adobe Express provided insights that informed style refinements."
@@ -19,27 +16,19 @@
     },
     {
       "type": "guideline",
-      "content": "The Spectrum 2 icon style aligns with contemporary UI and icon trends and is optimized for where the icons are viewed: displays across desktop and mobile. With a bigger focus on high-res screens, we've prioritized spacing and contrast for a more expressive range — leaving behind the problem of pixel-perfect snapping."
-    },
-    {
-      "type": "guideline",
-      "content": "We're also aligning the stroke weight into 4 subdivisions inside the pixel unit to create balanced stroke rendering with a 1.5 px stroke weight. This weight has been proven to work well with mobile retina screens, and it allows for a stronger appearance of the line renderings of icon shapes."
-    },
-    {
-      "type": "guideline",
-      "content": "Icons are outlined. They're mostly monochrome to allow for colored accents in badges for status updates like alerts, information, and notifications. Some icons also use fill and a stroke to illustrate a concept more clearly (for example, the favorite star rating, or third-party logos)."
+      "content": "The Spectrum 2 icon style aligns with contemporary UI and icon trends and is optimized for where the icons are viewed: displays across desktop and mobile. With a bigger focus on high-res screens, we've prioritized spacing and contrast for a more expressive range — leaving behind the problem of pixel-perfect snapping. We're also aligning the stroke weight into 4 subdivisions inside the pixel unit to create balanced stroke rendering with a 1.5 px stroke weight. This weight has been proven to work well with mobile retina screens, and it allows for a stronger appearance of the line renderings of icon shapes."
     },
     {
       "type": "guideline",
-      "content": "Occasionally, there are duotone icons to indicate a perceived change of direction, exclusion, transition, or speed (like in flip horizontal/vertical)."
+      "content": "Icons are outlined. They're mostly monochrome to allow for colored accents in badges for status updates like alerts, information, and notifications. Some icons also use fill and a stroke to illustrate a concept more clearly (for example, the favorite star rating, or third-party logos). Occasionally, there are duotone icons to indicate a perceived change of direction, exclusion, transition, or speed (like in flip horizontal/vertical). Various examples of Spectrum 2 icons.Similarities of icon styles across Spectrum and Adobe Express.How icons have evolved over time."
     },
     {
       "type": "guideline",
-      "content": "Characteristics.\n\nAdobe products often have complex controls, so our icon metaphors are **clear**, **functional**, and **additive to experiences**. They describe tools and topics as simply and accurately as possible. Icons that attempt to relay too much information often become busy and don't read well at small sizes.\n\nThe shapes of the icons themselves are based on predefined **key shapes** to ensure a balanced look and feel across interfaces."
+      "content": "Characteristics.\n\nAdobe products often have complex controls, so our icon metaphors are clear, functional, and additive to experiences. They describe tools and topics as simply and accurately as possible. Icons that attempt to relay too much information often become busy and don't read well at small sizes. The shapes of the icons themselves are based on predefined key shapes to ensure a balanced look and feel across interfaces. Examples of key shapes."
     }
   ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/icon-fundamentals/",
-  "lastUpdated": "2026-02-02",
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/icons-and-illustrations/icon-fundamentals",
+  "lastUpdated": "2026-09-04",
   "status": "published",
-  "tags": ["designing"]
+  "tags": ["icons", "outline", "monochrome", "stroke-weight", "iconography"]
 }

package/guidelines/illustration.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/illustration.json",
+  "name": "illustration",
+  "title": "Illustration",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Illustration" },
+    {
+      "type": "guideline",
+      "content": "Comparing Spectrum 1 and Spectrum 2.\n\nHere’s a summary of the main updates that you’ll notice with Spectrum 2 illustrations, compared to the style of Spectrum 1: Similar to icons and text, all linear illustrations now use Spectrum gray 800 instead of gray 500. This meets accessibility standards by ensuring visibility regardless of the background color. These illustrations have a much closer connection to the icon metaphors and forms, for a consistent and cohesive visual language. Linear illustrations feature rounder and friendlier forms, making them feel more approachable. The compositions are also less cluttered and more clear, to promote focus and scaleability. The S2 illustrations come in three sizes: S (48×48 px), M (96×96 px), and L (160×160 px). These sizes are in line with the spacing tokens, and provide more flexibility for layouts. With the introduction of gradient illustrations, there's now an option for illustrations with more color. Color creates more expressiveness and brand integration, as well as supports multiple levels of attention hierarchy."
+    },
+    {
+      "type": "guideline",
+      "content": "Spectrum 2 illustrations have two styles: linear (monochromatic) and gradient (color). Both have specific use cases. If you’re not sure about which style is appropriate for your use case, please reach out to the Spectrum Brand team for support. Do not create your own illustrations, or use 3rd-party assets. Illustrations are very visible parts of our design system that drive the consistent look and feel to our products, so they need to be used strategically and thoughtfully."
+    },
+    {
+      "type": "guideline",
+      "content": "The Spectrum 2 linear illustrations are an evolution of the Spectrum 1 outline style. The Spectrum 2 icons serve as the blueprint; they follow the same metaphors and are drawn in a similar way. Linear illustrations are monochromatic. They use the same color token as the icons (S2 / gray 800), and switch colors according to dark and light UI."
+    },
+    {
+      "type": "guideline",
+      "content": "Sizes.\n\nLinear illustrations come in three sizes: small (48×48 px), medium (96×96 px), and large (160×160 px). Small and medium are the most commonly used sizes; large is not used as often. For most use cases, the medium size works well across mobile, tablet, and desktop."
+    },
+    {
+      "type": "guideline",
+      "content": "Color.\n\nThe linear illustrations use Spectrum gray 800, and switch between light and dark UI. For production, the SVGs in the A4U libraries use embedded tokens, similar to the structure of the icons. This ensures that they can programmatically switch depending on UI brightness or color theme. The components in the Figma library use the S2 / Variables tokens."
+    },
+    {
+      "type": "guideline",
+      "content": "Naming convention.\n\nLinear illustrations use the following naming convention: Prefix identifies it as part of a larger group of assets: in this case, S2 (Spectrum 2). Type is the type of the asset: lin for linear illustration. Illustration name is in camel case, and there are no empty spaces or individual characters allowed. Illustration size is stated in pixels at @1x. Filetype suffix indicates the asset format, like SVG or PNG."
+    },
+    {
+      "type": "guideline",
+      "content": "Use cases.\n\nLinear illustrations are straightforward and clear UI illustrations for a variety of use cases, such as empty states or error messages. They support calls to action — like a drop zone illustration, or an empty state illustration — that explain the next steps for how to use the interface in order to get started or move forward. A good example of a use case for a linear illustration is with the illustrated message component."
+    },
+    {
+      "type": "guideline",
+      "content": "Sizes.\n\nGradient illustrations come in the same sizes as the linear illustrations: small (48×48 px), medium (96×96 px), and large (160×160 px). For most use cases, the medium size works well across mobile, tablet, and desktop."
+    },
+    {
+      "type": "guideline",
+      "content": "Colors.\n\nThe colors of the gradient illustrations use Spectrum’s 6.0.0 color system. They're tied to the different Adobe product categories and individual products. There are two gradients that can be used for surfaces that show different products, or that are not product-specific. The other gradients are tied to specific products or clouds. For example, blue is tied to the photography and digital imaging category (such as Photoshop, Lightroom, and Fresco), while green represents the 3D category (such as Substance 3D Stager and Substance 3D Designer). It’s essential to use the appropriate illustration colors according to the product categories. If the application is for multiple products, use one of the gradient swatches that incorporate the Adobe brand red. Do not use the category gradient sets as semantic colors to communicate meanings like errors (red), warnings (yellow), or successes (green)."
+    },
+    {
+      "type": "guideline",
+      "content": "Naming convention.\n\nGradient illustrations use the following naming convention: Prefix identifies it as part of a larger group of assets: in this case S2 (Spectrum 2). Type is the type of the asset: fill for gradient illustration. Illustration name is in camel case, and there are no empty spaces or individual characters allowed. Category differentiates the different gradient fill colors. The categories include: allproduct1, allproduct2, 3D, DC, drawing, DVA, express, EC, photo, and print. Illustration size is stated in pixels at @1x. Filetype suffix indicates the asset format, like SVG or PNG."
+    },
+    {
+      "type": "guideline",
+      "content": "Illustrations and attention hierarchy.\n\nThe different styles of illustrations are connected to the Spectrum 2 concept of attention hierarchy. Linear illustrations are elements that communicate lower attention, as they blend in well with the rest of the UI. They can be used multiple times in a layout without drawing too much attention. Gradient illustrations are high attention elements that should be used sparingly and selectively. Only one illustration, element, or group of elements should have high attention on a page. Learn more about this with the Spectrum 2 attention hierarchy guidelines."
+    },
+    {
+      "type": "guideline",
+      "content": "Use linear illustrations for errors or critical messages.\n\nErrors or critical messages should only use linear illustrations. Gradient illustrations use colors that can be misunderstood as semantic colors (e.g., green for positive, red for negative). They also have an upbeat and inspirational tone, which isn’t appropriate in situations where a user may be frustrated by something that’s an inconvenience or is disruptive to them in accomplishing their work."
+    },
+    {
+      "type": "guideline",
+      "content": "Use linear style when showing several illustrations together.\n\nThe linear illustration style works well for layouts that feature a number of illustrations together (such as a collection of cards). Linear illustrations draw a lower level of attention and blend in well with the UI, so it’s appropriate to use them in a collection of elements. Gradient illustrations draw a lot of attention in multiples, so they need to be used sparingly and sparsely."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t resize illustrations.\n\nDon’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t create your own linear illustrations.\n\nIt’s essential to have consistency in tone and metaphors across all Adobe products. Don’t create your own linear illustrations or alter existing ones. If you need a new linear illustration, make a request using Workfront."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t recolor illustrations.\n\nAlways use gray 800 for the illustration color. Using semantic colors (red, orange, green, blue) can help reinforce meaning, but should be considered on a case-by-case basis."
+    },
+    {
+      "type": "guideline",
+      "content": "Use gradient illustrations thoughtfully.\n\nGradient illustrations are high attention elements in the layout. Use them strategically and thoughtfully to draw the user’s attention and to provoke a delightful moment."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t show more than one gradient illustration at a time.\n\nGradient illustrations draw more attention because they’re very colorful. Using more then one in a given view will make the UI too busy and too loud. Use gradient illustrations sparingly to guide a user’s attention to engaging, high-value actions such as uploads, starting projects, or commenting."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t use gradient illustrations for error or critical messages.\n\nGradient illustrations incorporate product category colors, and also include colors that have semantic meanings in Spectrum: red, orange, or green. It creates inconsistency and confusion to have an error message or a critical alert in green (a color has a positive semantic meaning). Use gradient illustrations when you want to emphasize positive actions. Gradient illustrations have an upbeat and inspirational tone, which isn’t appropriate in situations where a user may be frustrated by something that’s an inconvenience or is disruptive to them in accomplishing their work."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t create your own gradient illustrations.\n\nIt’s essential to have consistency in tone and metaphors across all Adobe products. Don’t create your own gradient illustrations or alter existing ones. If you need a new gradient illustration, make a request using Workfront."
+    },
+    {
+      "type": "guideline",
+      "content": "Use the correct colors for your product.\n\nThe colors in gradient illustrations are connected to the product categories. For example, an illustration for a Substance 3D product should use the Substance 3D green colors. Do not use different colors than those of your product category. Reach out to the Spectrum Brand team for guidance about the appropriate colors for your use case."
+    },
+    {
+      "type": "guideline",
+      "content": "Test if gradient illustrations work well in your layout.\n\nIt’s highly recommended to test gradient illustrations as you’re designing your layout. They’re very expressive and colorful, so it’s important to determine how they complement (or don’t) different communication points (e.g., user-generated content, onboarding, feature banners, upsells, and more). If gradient illustrations are making the layout too noisy, use linear illustrations instead."
+    },
+    {
+      "type": "guideline",
+      "content": "Thematic banners are descriptive and represent a specific topic or feature. Similar to the gradient illustrations, they’re either connected to the product brand categories by color, or they use the generic gradient swatches. These banners use the same shapes, metaphors, and elements as the linear illustrations, but they have a distinct style that is combined with the gradients and colors of the gradient illustrations. With their size, usage of color, and high editorial quality, thematic banners are high on the attention hierarchy scale. In layout, they work best when used to promote positive and high-impact moments, such as announcing new features. Because of this, they should be used sparingly. Thematic banners are created on a case-by-case basis by the Spectrum Brand team. You can request thematic banners through this Workfront request form. There is no asset library for thematic banners because they have unique needs for each product use case."
+    },
+    {
+      "type": "guideline",
+      "content": "Before you work with these illustrations, please familiarize yourself with the usage guidelines here. You’ll especially need to understand the differences in how to use the linear and gradient illustrations. For new or existing illustrations, please submit a request through this Workfront form. You can also reach out to the Spectrum Brand team with any questions on Slack in #product-branding or by email. To view existing S2 Illustrations, visit the S2 / Illustrations library in Figma. The assests from this library are also available in A4U for production and engineering assets (VPN access required)."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/visual-language/illustration",
+  "lastUpdated": "2026-08-19",
+  "status": "published"
+}