` as a button, you give it the correct [aria role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role).\n\nThe copy inside buttons should be concise and confirm the action a user is taking.\n\n### Themes\n\nA theme may be applied to a button to change its appearance. o-buttons provides some themes by default:\n\n| Theme | Selector | Works With Types | Brand Support |\n| ------- | ------------------- | ------------------ | -------------- |\n| inverse | .o-buttons--inverse | primary, secondary, ghost | core, internal |\n| mono | .o-buttons--mono | primary, secondary, ghost | core, internal |\n| b2c | .o-buttons--b2c | primary | core |\n| professional | .o-buttons--professional | primary, secondary, ghost | core |\n| professional-inverse | .o-buttons--professional-inverse | primary, secondary, ghost | core |\n| ft-live | .o-buttons--ft-live | primary, secondary, ghost | core |\n\n```html\n\n\n```\n\nSass users may create [custom themes](#custom-themes).\n\n### Sizes\n\nAny button may be made larger using the `o-buttons--big` modifier class.\n\n```html\n\n```\n\n### Icons\n\nTo add an icon to your button add the class `o-buttons-icon` and `o-buttons-icon--{icon-name}` to your button.\n\n[Sass](#sass) users may output any icon from the [fticons](https://registry.origami.ft.com/components/fticons/) set. However if you're using the [Build Service](https://www.ft.com/__origami/service/build/) a limited number of button icons are available. Limiting the number of icons keeps the CSS bundle smaller, but if you need an icon button that we don't currently support then please contact the Origami team:\n- arrow-left\n- arrow-right\n- upload\n- tick\n- plus\n- warning\n- arrow-down\n- arrow-up\n- grid\n- list\n- edit\n- download\n- search\n- refresh\n- cross\n\n```html\n\n\n```\n\nIf you would like your button to display only an icon, add the class `o-buttons-icon--icon-only` and provide a visually hidden label for screen-reader users with `o-buttons-icon__label`.\n\n```html\n\n```\n\n### Groups\n\nWrap buttons with `.o-buttons-group` to group them together:\n\n```html\n\n\t\n\t\n\t\n
\n```\n\n### Pagination\n\nFor a pagination style wrap your buttons in `.o-buttons-pagination`. Most pagination usecases use an anchor `a` tags for links which look like buttons instead of a `button` tag. When using an anchor tag in pagination do not use the `aria-selected` data attribute. Instead use `aria-current=\"page\"` to indicate the current page, this will highlight the button for the current page visually and to screen readers.\n\nThe following markup example shows pagination for 20 pages, where the 14th page is the current page. Following the [pagination rules](#pagination-rules) we recommend displaying no more than 7 pages and using the ellipsis element to show hidden results.\n\n```html\n\n```\n\n#### Pagination Rules\n\nThe number of pages to display is not enforced by Origami. However we recommend the following:\n- Show no more than 7 pages at a time. When there are more than 7 pages, hide more pages behind the pagination ellipsis in the following way. Given:\n\t- The selected page is below 3 show ellipsis with 3 pages either side.\n\t- The selected page is one of the last 2 pages show ellipsis with 3 pages either side.\n\t- The 3rd page is selected show 4 pages, the ellipsis, and 2 more pages.\n\t- The 3rd from last page is selected show 2 pages, the ellipsis, and 4 more pages.\n\t- The selected page is more than 3 from the first and last page show the first page, ellipsis, three pages, ellipsis, and the last page.\n\nFor an example see the [pagination demos in the Origami registry](https://registry.origami.ft.com/components/o-buttons@6.0.19#demo-pagination-layout).\n\n#### Pagination Theme\n\nA theme modifier such as `o-buttons--inverse` may be added to the buttons within a pagination block.\n\n#### Pagination Size\n\nBig buttons may also be used in a pagination style. Add the `o-buttons--big` modifier to each button and `o-buttons-pagination__ellipsis--big` to the ellipsis element.\n\n```html\n\n```\n\n### Disabled\n\nAvoid disabled buttons unless user research shows they improve your interface. Disabled buttons have [poor contrast which makes them difficult to read](#references). They also [do not give feedback to a user why they are disabled](#references).\n\nTo make a button disabled add the `disabled` attribute. To visually hide the disabled button until it is active add the class `o-buttons--hide-disabled`.\n\n```html\n\n\n\n\n\n```\n\n## Sass\n\nTo output default o-buttons CSS make a single call to the primary mixin `oButtons`. It is recommended that you pass an options map as the first argument to include only the button styles you need. Without the options map, all o-buttons styles are included.\n\n```scss\n@include oButtons($opts: (\n\t'sizes': ('big'), // e.g .o-buttons--big\n\t'types': ('primary', 'secondary', 'ghost'), // e.g .o-buttons--primary\n\t'themes': ('mono', 'inverse', 'b2c', 'professional', 'professional-inverse', 'ft-live'), // e.g .o-buttons--inverse\n\t'icons': ('arrow-left', 'arrow-right', 'search'), // any fticons, e.g .o-buttons-icons.o-buttons-icons--search\n\t'pagination': true, // .o-buttons-pagination\n\t'groups': true // .o-buttons-group\n));\n```\n\n### Custom Themes\n\nTo create a new button theme call `oButtonsAddTheme` with the colour of your theme along with the types of buttons and icons you would like to use with your theme, if any.\n\n- name: The name of your theme. This is used for the modifer class output `o-buttons--{name}`.\n- opts: A map of options for your theme. Keys include `color` and `context`.\n\t- color: The main colour of your button. Any o-colors palette colour name.\n\t- context (optional): The background colour your button is placed on. Defaults to the page colour (paper for the core brand, white otherwise). This is used to confirm accessibility and in some cases changes the colour of the button.\n- types: A list of button types your theme is used with.\n- icons: A list of icons your theme is used with. Any [fticons](https://registry.origami.ft.com/components/fticons/) icon name.\n\n```scss\n/// .o-buttons--my-special-button\n@include oButtonsAddTheme(\n\t$name: 'my-special-button',\n\t$opts: ('color': 'claret-80'),\n\t$types: ('primary', 'secondary'),\n\t$icons: ('arrow-up', 'arrow-down')\n);\n```\n\n### Custom Markup\n\nWe recommend using `o-buttons` markup as this encourages CSS reuse and smaller bundle sizes. If you are unable to update your markup to use `o-buttons` classes, including those generated by `oButtonsAddTheme`, use `oButtonsContent`:\n\n```scss\n.my-button {\n\t@include oButtonsContent($opts: ('type': 'primary'));\n}\n```\n\n```scss\n.my-icon-button {\n\t@include oButtonsContent($opts: (\n\t\t'type': 'primary',\n\t\t'icon': 'arrow-right'\n\t));\n}\n```\n\n```scss\n.my-lemon-button {\n\t@include oButtonsContent($opts: (\n\t\t'type': 'primary',\n\t\t'theme': ('color': 'lemon')\n\t));\n}\n```\n\n`oButtonsContent` has options to recreate all buttons, including for different sizes and icon only buttons. See the [o-buttons SassDoc](https://registry.origami.ft.com/components/o-buttons/sassdoc) for more details and examples.\n\n## References\n\n- Hampus Sethfors explains the issues with disabled buttons in more detail in an [axesslab.com article](https://axesslab.com/disabled-buttons-suck/). In the article Hampus suggests alternative design approaches for common uses of disabled buttons.\n\n## Migration\n\nState | Major Version | Last Minor Release | Migration guide |\n:---: |:-------------:| :---: |:------------------------------------------------------------:\n✨ active | o3 | N/A | [migrate to o3](MIGRATION.md#migrating-from-v7-to-o3-button@3) |\n⚠ maintained | 7 | N/A | [migrate to v7](MIGRATION.md#migrating-from-v6-to-v7) |\n╳ deprecated | 6 | 6.2 | [migrate to v6](MIGRATION.md#migrating-from-v5-to-v6) |\n╳ deprecated | 5 | 5.16 | [migrate to v5](MIGRATION.md#migrating-from-v4-to-v5) |\n╳ deprecated | 4 | 4.5 | - |\n╳ deprecated | 3 | 3.1 | - |\n╳ deprecated | 2 | 2.0 | - |\n╳ deprecated | 1 | 1.8 | - |\n\n\n## Contact\n\nIf you have any questions or comments about this component, or need help using it, please either [raise an issue](https://github.com/Financial-Times/o-buttons/issues), visit [#origami-support](https://financialtimes.slack.com/messages/origami-support/) or email [Origami Support](mailto:origami-support@ft.com).\n\n***\n\n## Licence\n\nThis software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).\n","readmeFilename":"README.md"}