diff --git a/.eslintrc.js b/.eslintrc.js index 18d810644c..fb5d1d8170 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -216,6 +216,7 @@ module.exports = { // Ignore components added as shortcodes so they don't get marked as undefined // TODO: remove the components that aren't shortcodes, just haven't been added yet Callout: false, + ComponentStatus: false, Do: false, Dont: false, FancyLink: false, diff --git a/.github/styles/Kiwi/Acronyms.yml b/.github/styles/Kiwi/Abbreviations.yml similarity index 94% rename from .github/styles/Kiwi/Acronyms.yml rename to .github/styles/Kiwi/Abbreviations.yml index 9aa6745e98..177eb0461a 100644 --- a/.github/styles/Kiwi/Acronyms.yml +++ b/.github/styles/Kiwi/Abbreviations.yml @@ -5,7 +5,7 @@ level: suggestion ignorecase: false # Ensures that the existence of 'first' implies the existence of 'second'. first: '\b([A-Z]{3,5})\b' -second: '(?:\b[a-z]+ )+\(([A-Z]{3,5})\)' +second: '(?:\b[a-zA-Z]+ )+\(([A-Z]{3,5})\)' # ... with the exception of these: exceptions: - API diff --git a/.github/styles/Kiwi/Contractions.yml b/.github/styles/Kiwi/Contractions.yml index 565c0dde97..c132f4d441 100644 --- a/.github/styles/Kiwi/Contractions.yml +++ b/.github/styles/Kiwi/Contractions.yml @@ -26,3 +26,4 @@ swap: when is: when's where is: where's will not: won't + you are: you're diff --git a/.github/styles/Kiwi/EmDash.yml b/.github/styles/Kiwi/EmDash.yml index db46fdb149..d6bbabc3fb 100644 --- a/.github/styles/Kiwi/EmDash.yml +++ b/.github/styles/Kiwi/EmDash.yml @@ -4,5 +4,7 @@ link: 'https://orbit.kiwi/content/grammar-and-mechanics/#punctuation' scope: paragraph level: error tokens: - - '(?` @@ -21,7 +21,11 @@ export const LevelDiv = styled.div` `} `; -export default ({ level }) => { +interface ElevationLevelProps { + level: 1 | 2 | 3 | 3.5 | 4 | 4.5 | 5 | 5.5 | 6; +} + +export default ({ level }: ElevationLevelProps) => { let backgroundColor = theme.orbit.paletteWhite; let border = "none"; let boxShadow = "none"; diff --git a/docs/src/components/Github/data.json b/docs/src/components/Github/data.json index e58fa37fc5..949ed75267 100644 --- a/docs/src/components/Github/data.json +++ b/docs/src/components/Github/data.json @@ -7,7 +7,7 @@ "dribbble": "", "github": "https://github.com/CollierCZ", "twitter": "", - "website": "" + "website": "https://collier.cz/" }, { "id": "will", @@ -32,7 +32,7 @@ { "id": "vepor", "name": "Luděk Vepřek", - "info": "Luděk leads our team. He is responsible for cross-platform API consistency between different implementations of Orbit components", + "info": "Luděk leads our team. He is responsible for cross-platform API consistency between different implementations of Orbit components.", "position": "Engineering Lead", "dribbble": "", "github": "https://github.com/vepor", diff --git a/docs/src/components/Placeholder.tsx b/docs/src/components/Placeholder.tsx new file mode 100644 index 0000000000..55a5b813a6 --- /dev/null +++ b/docs/src/components/Placeholder.tsx @@ -0,0 +1,2 @@ +const Placeholder = ({ children }) => children; +export default Placeholder; diff --git a/docs/src/documentation/01-getting-started/01-for-designers/01-kiwi.mdx b/docs/src/documentation/01-getting-started/01-for-designers/01-kiwi.mdx index d72e547397..40f26df0aa 100644 --- a/docs/src/documentation/01-getting-started/01-for-designers/01-kiwi.mdx +++ b/docs/src/documentation/01-getting-started/01-for-designers/01-kiwi.mdx @@ -14,7 +14,7 @@ We use Figma for all our entire design workflow. Since it's a larger topic, we've set up a set of guides on [working with Figma](https://orbit.kiwi/?page_id=7603). -- If you run into any issues, use the **\#plz-figma** channel on Slack. +- If you run into any issues, use the **#plz-figma** channel on Slack. ## Fonts diff --git a/docs/src/documentation/01-getting-started/01-for-designers/02-open-source.mdx b/docs/src/documentation/01-getting-started/01-for-designers/02-open-source.mdx index 0c63167b01..2d6c3117fc 100644 --- a/docs/src/documentation/01-getting-started/01-for-designers/02-open-source.mdx +++ b/docs/src/documentation/01-getting-started/01-for-designers/02-open-source.mdx @@ -11,13 +11,9 @@ we provide our Figma UI kit as files for you to download. To access our library, duplicate the files you can find at our community profile. - + -These will appear as in your Drafts. +These appear in your Drafts. Now you can work with them to create your own designs. If you have a team plan, you can also use the files as a library. @@ -25,7 +21,7 @@ See the [Figma docs for how to publish the files to a library](https://help.figm -Currently, Figma does not provide notifications when our public files are updated. +Currently, Figma doesn't provide notifications when our public files are updated. To make sure you stay up to date, check the _Last updated_ date on the files at our community profile and [follow us on Twitter](https://twitter.com/OrbitKiwi). @@ -33,14 +29,14 @@ and [follow us on Twitter](https://twitter.com/OrbitKiwi). ## Font -By default, our libraries use Circular Pro, which is not an open font. +By default, our libraries use Circular Pro, which isn't an open font. If you have a license for Circular Pro, you can use Orbit with Circular Pro. -Don't forget to [buy a license](https://lineto.com/the+fonts/font+categories/text+fonts/circular/) for your domains. +Don't forget to [buy a license](https://lineto.com/the+fonts/font+categories/text+fonts/circular/) for your domains. -If you do not have a license, you can replace it with Roboto, a free font from Google. +If you don't have a license, you can replace it with Roboto, a free font from Google. You can [download Roboto from Google Fonts](https://fonts.google.com/specimen/Roboto). diff --git a/docs/src/documentation/01-getting-started/02-for-developers.mdx b/docs/src/documentation/01-getting-started/02-for-developers.mdx index a7ec66a132..7c71b983fc 100644 --- a/docs/src/documentation/01-getting-started/02-for-developers.mdx +++ b/docs/src/documentation/01-getting-started/02-for-developers.mdx @@ -5,7 +5,7 @@ excerpt: Our components are served as an npm package. [![orbit-components](https://orbit.kiwi/files/orbit-components.png)](https://orbit.kiwi) -[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/) +[![Lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/) **Orbit-components is a React component library which provides developers with the easiest possible way of building Kiwi.com products.** @@ -88,7 +88,7 @@ yarn add @types/styled-components -D ## Contributing -We are working on making this project a fully open source. +We're working on making this project a fully open source. e appreciate any contributions you might make. [Bug reports](https://github.com/kiwicom/orbit/issues/new?template=bug_report.md) and [feature requests](https://github.com/kiwicom/orbit/issues/new?template=feature_request.md) are welcome, diff --git a/docs/src/documentation/01-getting-started/03-github.mdx b/docs/src/documentation/01-getting-started/03-github.mdx index 5a69124021..3785aba735 100644 --- a/docs/src/documentation/01-getting-started/03-github.mdx +++ b/docs/src/documentation/01-getting-started/03-github.mdx @@ -3,20 +3,17 @@ title: GitHub repos & resources excerpt: List of repositories related to Orbit design system. --- -## Github Repositories +## GitHub monorepo -All Orbit Github repositories are public and available as NPM packages. - -### Orbit monorepo - -Orbit has a single repository that contains all the important packages. +Orbit has a single repository that contains all important packages +(available via npm) and documentation. -#### React components +### React components -The Orbit Components package stores all React components along with API -documentation. +The Orbit Components package stores all React components +along with API documentation. -#### Orbit Design Tokens +### Orbit Design Tokens The Orbit Design Tokens package stores all visual UI attributes. -Available as an npm package. diff --git a/docs/src/documentation/01-getting-started/04-support/01-kiwi.mdx b/docs/src/documentation/01-getting-started/04-support/01-kiwi.mdx index fe64b543b6..ce6db45342 100644 --- a/docs/src/documentation/01-getting-started/04-support/01-kiwi.mdx +++ b/docs/src/documentation/01-getting-started/04-support/01-kiwi.mdx @@ -3,56 +3,52 @@ title: For Kiwi.com --- Slack is Kiwi.com's main platform for communication, -so it's only understandable that everything important that is happening around Orbit is also on Slack. +so it's only understandable that everything important that's happening around Orbit is also on Slack. ## Slack ### Groups -We also have four groups you can use to tag members of Orbit team: +We have groups you can use to tag members of the Orbit team: -- **\@orbit** -- tags all Orbit members -- **\@orbitdesign** -- tags all designers behind Orbit -- **\@orbitreact** -- tags all React maintainers of Orbit components -- **\@orbitdocs** -- tags all maintainers of Orbit documentation +- **@orbit**: tags all Orbit members +- **@orbitdesign**: tags all designers behind Orbit +- **@orbitdevs**: tags all maintainers of Orbit components ### Channels See all of our channels and what they're for. -#### \#plz-orbit +#### `#plz-orbit` If you need to request some change in Orbit components, Sketch UI kit, etc., -this channel is one you are looking for. +this is the channel you're looking for. -#### \#orbit-announcements +#### `#orbit-announcements` -The main channel with general information about Orbit -- component releases, updates of Sketch UI library, ... +The main channel with general information about Orbit: +component releases, updates to the Figma libraries, and so on. -#### \#orbit-react +#### `#orbit-react` The channel where we discuss everything connected to developing Orbit components in React. -#### \#orbit-mobile-native +#### `#orbit-standup` -The channel where we discuss everything related to the native mobile variation of Orbit. +Team channel where all team members write their daily activities. -#### \#orbit-standup - -Team channel where all team members write their daily standups. - -#### \#orbit-documentation +#### `#orbit-documentation` The channel where we discuss everything related to documentation. -#### \#orbit-github-log +#### `#orbit-github-log` -Log of everything that is happening in [Orbit Github repositories](https://orbit.kiwi/getting-started/github-repos-resources/). +A log of everything that's happening in [Orbit GitHub repositories](https://orbit.kiwi/getting-started/github-repos-resources/). -## Bug reporting on Github +## Bug reporting on GitHub If you found any bugs in our components, -report them [on Github](https://github.com/kiwicom/orbit-components/issues) and we'll fix them asap. +report them [on GitHub](https://github.com/kiwicom/orbit-components/issues) and we'll fix them asap. It's the highest priority to have Orbit working as expected. -## Bug reporting on Github +## Bug reporting on GitHub -If you found any bugs in our components, report them [on -Github](https://github.com/kiwicom/orbit-components/issues) and we'll -fix them asap. It's the highest priority to have Orbit working as -expected. +If you found any bugs in our components, +report them [on GitHub](https://github.com/kiwicom/orbit-components/issues) +and we'll fix them asap. +It's the highest priority to have Orbit working as expected. - - -## Core team - -### Design & Product - -![Aaron](https://orbit.kiwi/files/aaron.png) - -Aaron Collier, Writer - -Aaron is responsible for our documentation. -He maintains and improves every part of orbit.kiwi to be as useful as possible. - - - -![Will](https://orbit.kiwi/files/2019/09/will.png) - -William Kolmačka, Product Designer - -Will is responsible for the design part of Orbit. -He works on and maintains UI kit and occasionally helps with the coding of components in React. - - - -![Milan](https://orbit.kiwi/files/milan.jpeg) - -Milan Seitler, Product Designer - -Milan is part of the core team for design. He contributes to the UI kit. - - - -![Luděk](https://orbit.kiwi/files/2019/09/vepor.jpeg) - -Luděk Vepřek, Team Lead - -Luděk leads our team. -He is responsible for cross-platform API consistency between different implementations of Orbit components. - - - -### Engineering - -![Victor](https://orbit.kiwi/files/victor-genaev.png) - -Victor Genaev, Software Engineer - -Victor is one of the core component contributors to the React implementation of Orbit -and is responsible for refactoring larger components. - - - -![Matija Marohnić](https://orbit.kiwi/files/matija.jpeg) - -Matija Marohnić, Software Engineer - -Matija has extensive knowledge of frontend ecosystems. -Besides working on React components, -he also focuses on internal and external tooling to improve the overall developer experience with Orbit. - - - -## Former members - -![Filip D](https://orbit.kiwi/files/2019/09/filip-d.png) - -Filip Daniško, Software Engineer - -Filip maintained mostly React components and was also responsible for the whole accessibility aspect of Orbit. - - - -![Tomáš](https://orbit.kiwi/files/2019/09/tom.png) - -Tomáš Hapl, React Engineer - -Tom, besides his work on React components, was the main maintainer of Orbit packages. -He empowered our developers by providing smooth-working tooling and was the main contributor to the Orbit Themer. - - - -![Filip M](https://orbit.kiwi/files/2019/09/filip-m.jpeg) - -Filip Mešša, React Native Engineer - -Filip has extensive experience with building React Native components for different Kiwi.com products -and he used this experience to make React Native components more stable and usable. - - - -![Daniel](https://orbit.kiwi/files/2019/09/daniel.png) - -Daniel Spitzer, React Native Engineer - -Daniel was in the core team for extending Orbit to React Native. -He worked from Barcelona and was also responsible for React Native releases. - - - -![Jan Toman](https://orbit.kiwi/files/2019/09/honza-t.png) - -Jan Toman, Product Lead - -Jan managed Orbit in terms of product and design direction and maintained the roadmap. -He enjoys design contributions, mostly to new components. - - - -![Jan V](https://orbit.kiwi/files/2019/09/honza-v.jpeg) - -Jan Václavík, React Native Lead - -Jan led our React Native developers -and was one of the core component contributors to the React Native implementation of Orbit. - - - ## All contributors -From small reviews or additions to contributions of whole components. We really appreciate all your efforts when helping us to make Orbit better +From small reviews or additions to contributions of whole components. +We really appreciate all your efforts when helping us to make Orbit better 👏 ### React components - + Thanks to all these folks for caring, your contribution helps to all Orbit consumers. diff --git a/docs/src/documentation/02-foundation/01-principles/01-orbit-principles.mdx b/docs/src/documentation/02-foundation/01-principles/01-orbit-principles.mdx index 8807d0a781..6172077f15 100644 --- a/docs/src/documentation/02-foundation/01-principles/01-orbit-principles.mdx +++ b/docs/src/documentation/02-foundation/01-principles/01-orbit-principles.mdx @@ -13,7 +13,7 @@ We elevate user experience and increase the speed and efficiency of how we desig > we all will make travel better. > Together. -Although the components are the core part of Orbit, we are not just another component library. +Although the components are the core part of Orbit, we're not just another component library. We took years of experience of building travel product and baked it into our components, from accessibility and internalization to advanced theming and offering travel-specific components. @@ -21,14 +21,14 @@ from accessibility and internalization to advanced theming and offering travel-s These are our values to which we refer when we build and maintain Orbit. -With absolute honesty, Orbit is not currently fully compliant with some of our principles, +With absolute honesty, Orbit isn't currently fully compliant with some of our principles, but we're working on it every day. These principles help us to keep on track and be focused on the right things. ### Find the best middle ground There are 4 key aspects when working on Orbit. -Our goal is to meet somewhere in the middle---so everything we do is not just consistent or composable, +Our goal is to meet somewhere in the middle---so everything we do isn't just consistent or composable, but improves the work of our designers and developers and is maintainable in the long-term. ![Our goal sits at the overlap of consistency, designer/developer experience, maintainability, and composability.](../../assets/foundation/venn.png) @@ -37,7 +37,7 @@ but improves the work of our designers and developers and is maintainable in the Transparency is the key to success. That's why we have a [public roadmap](/roadmap/) and open feedback channels. -But we are trying to go further. +But we're trying to go further. We document our design decisions so we can reference to them in discussions and not reinvent the wheel again by discussing stuff repeatedly and without historical context. @@ -61,8 +61,8 @@ But, our focus is on using patterns and vocabulary that are familiar to our user ### Give consumers just enough control -The priority of Orbit consumers will be always to deliver the feature they need to work on--- -and they expect Orbit to be a tool that just works. +The priority of Orbit consumers is always to deliver the feature they need to work on. +And they expect Orbit to be a tool that just works. Give consumers delightful components and provide enough flexibility in how to assemble them for the specific use case they have. Ensure consistency in visual interactions, but allow consumers to extend components by their own actions. @@ -70,7 +70,7 @@ Ensure consistency in visual interactions, but allow consumers to extend compone ### Guide with documentation We decided to not document obvious things as is the visual style of components. -The purpose of our documentation is to be a partner who will help solve a problem when people build with Orbit. +The purpose of our documentation is to be a partner who helps solve a problem when people build with Orbit. We always aim to make our documentation available at the right moment and in the right context. ### Set appropriate defaults diff --git a/docs/src/documentation/02-foundation/01-principles/02-ui-kit-principles.mdx b/docs/src/documentation/02-foundation/01-principles/02-ui-kit-principles.mdx index 224c4faf12..2b30dc6562 100644 --- a/docs/src/documentation/02-foundation/01-principles/02-ui-kit-principles.mdx +++ b/docs/src/documentation/02-foundation/01-principles/02-ui-kit-principles.mdx @@ -12,9 +12,9 @@ what can be combined, and what can't. All components need to have our design decisions baked into them and only give a list of variations to choose from. -This will allow even less experienced visual designers to build beautiful products with Orbit. +This enables even less experienced visual designers to build beautiful products with Orbit. -### Practical tips +### Practical tips: visual decisions - If possible, have every component variation as a separate component or symbol. - Use overrides only for the component's content: texts, labels, icons, and illustrations. @@ -28,7 +28,7 @@ Switching between variations or removing default values takes a few seconds for If possible, even default content should help people with their design work, for example in nudging them to the mechanics of our grammar. -### Practical tips +### Practical tips: defaults - Mobile-first always: all components need to be in the size and look for mobile and have desktop, @@ -38,7 +38,7 @@ for example in nudging them to the mechanics of our grammar. - Sort components alphabetically at the root level, but by the most frequently used variations at the second level. This should help consumers find the right component quickly and then use its most common variation. -- Never use Lorem ipsum or any other variation of dumb content. +- Never use `Lorem ipsum` or any other variation of dumb content. - Use default content to help designers with micro-copy, for Alerts, for example, use a title and description to explain the purpose of each. @@ -48,12 +48,12 @@ There's a lot to think about when working with a UI kit. Remove moving parts as much as possible. Consistent naming and scope for our components should help everyone. -### Practical tips +### Practical tips: consistency - Have every component available for all platforms. If it's specific, document it and provide an alternative for specific platforms. - Use the same names for components and their parts in the design tool as in code. - This will help make handover between design and code smoother. + This helps make handover between design and code smoother. ## Favor usability over maintainability @@ -65,8 +65,8 @@ Using the Orbit UI kit should be easy and intuitive so any designer can start using it without extensive training. All edge cases or exceptions should be documented, ideally with examples. -### Practical tips +### Practical tips: usability -- Use guides to explain the alignment or composability of more complex components. +- Use guides to explain how to align or compose more complex components. - Speed up designers' workflow by providing larger reusable blocks as separate components (such as Login, App Frame) that are intended to be broken and adjusted. diff --git a/docs/src/documentation/02-foundation/02-accessibility.mdx b/docs/src/documentation/02-foundation/02-accessibility.mdx index 9f8c132512..21bc3b9950 100644 --- a/docs/src/documentation/02-foundation/02-accessibility.mdx +++ b/docs/src/documentation/02-foundation/02-accessibility.mdx @@ -21,14 +21,14 @@ excerpt: We build Orbit to ensure all users have the most pleasant experience po - Not perfectly calibrated glasses or just tired eyes - Non-quality displays in foreign countries - Non-stable environment, - like a bus or subway where you are balancing in a crowd + like a bus or subway where you're balancing in a crowd and need to find information quick -## Quick overview of WCAG 2.1 +## Quick overview of accessibility guidelines The Web Content Accessibility Guidelines (WCAG) are a single shared standard for web content accessibility. Going through the [WCAG specifications](https://www.w3.org/TR/WCAG21/) might seem, well, overwhelming. -But they are the most complete source for web accessibility. +But they're the most complete source for web accessibility. And navigating them can be easier then you might think. Rather than jumping into the complete specifications, go with a [quick reference guide](https://www.w3.org/WAI/WCAG21/quickref/). @@ -48,7 +48,7 @@ Learn more: As Orbit, we try our best to have accessible components from the get go and abstract as much we can for developers. -For example, we have a few components that will help you to make your websites more accessible. +For example, we have a few components that help you to make your websites more accessible. @@ -62,14 +62,14 @@ However, we can't do everything as making products accessible is a team effort. Below, you can find a list of current components where we need your help to ensure proper accessibility support. -| React Component | What Orbit offers | What you need to do | -| ----------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -| Badge | Screen reader support | Fill `ariaLabel` if there is a need for more information than you can fit in `content` | -| Button | Screen reader/keyboard navigation support | Read about [Button's multiple accessibility properties](/components/action/button/react/#accessibility) | -| ButtonLink | Screen reader/keyboard navigation support | Read about [ButtonLink's multiple accessibility properties]/components/action/buttonlink/react/#accessibility) | -| Card | Screen reader/keyboard navigation support | Use the `dataA11ySection` property when needed | -| Heading | Screen reader support | Use the `dataA11ySection` property when needed | -| NotificationBadge | Screen reader support | Fill `ariaLabel` if there is a need for more information than you can fit in `content` | +| React Component | What Orbit offers | What you need to do | +| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| Badge | Screen reader support | Fill `ariaLabel` if there is a need for more information than you can fit in `content` | +| Button | Screen reader/keyboard navigation support | Read about [Button's multiple accessibility properties](/components/action/button/react/#accessibility) | +| ButtonLink | Screen reader/keyboard navigation support | Read about [ButtonLink's multiple accessibility properties](/components/action/buttonlink/react/#accessibility) | +| Card | Screen reader/keyboard navigation support | Use the `dataA11ySection` property when needed | +| Heading | Screen reader support | Use the `dataA11ySection` property when needed | +| NotificationBadge | Screen reader support | Fill `ariaLabel` if there is a need for more information than you can fit in `content` | ## Screen readers (assistive technologies) @@ -84,7 +84,7 @@ Understanding the user context is the first step to being able to develop and de Luckily, all major operating systems already have a screen reader included, so you can just open it, follow the basic tutorial, and go on the web. -Mentioning the tutorial here is not a coincidence. +Mentioning the tutorial here isn't a coincidence. Screen readers are powerful tools with a lot of interesting features. They allow users to jump to headings, find the closest buttons, and lot more. To get better idea of what screen readers can do for a user, @@ -122,14 +122,15 @@ With accessibility regarding color, there are two main parts to keep in mind. Orbit provides an [accessible palette of colors](/foundation/color/). -_Disclaimer: we know about slight contrast issues in the product color and we are working toward fixing that._ +> Disclaimer: we know about slight contrast issues in the product color +> and we're working toward fixing that. Tip: Avoid using pure black text on a pure white background as it's difficult to read for dyslexic users. The combination of these colors causes the words to blur together. ### Convey information with more than just color -A message conveyed with color alone will be completely lost for some users. +A message conveyed with color alone is completely lost for some users. For example, don't indicate an error only with red, as the inability to distinguish red and green is the most common type of color blindness. @@ -148,7 +149,7 @@ and the spacing around the text makes it easy to distinguish what should be read Having a clear base size for the text enables you to base other sizing and spacing relative to that. See the [Typography section](/foundation/typography/) for how it works in Orbit. -Keep in mind that many users will use zoom and other technology +Keep in mind that many users use zoom and other technology to resize the text to fit their needs. Make sure your content works with no overlapping or need to scroll horizontally, even with the text at 200% of the base size. @@ -159,7 +160,7 @@ Proper spacing of lines helps readers track their progress through lines and recognize when they've reached the end of a paragraph. This means it's important to think about spacing both within and between paragraphs. -Within a paragraph, you want to aim for a line height that is about 1.5 times the font size. +Within a paragraph, you want to aim for a line height that's about 1.5 times the font size. Spacing between paragraphs and other elements should be enough to distinguish different elements while keeping related elements connected. @@ -170,7 +171,7 @@ See the [section on spacing](/foundation/spacing/) for more on the Orbit system. Long lines of text can be hard to follow and make readers lose their place in the text. With shorter lines, it's easier to flow from one line to the next. -Make sure your lines do not exceed 80 characters +Make sure your lines don't exceed 80 characters (or 40 for Chinese, Japanese, or Korean characters as those are about twice as wide). Lines can be shorter as well, down to 50 (or 25) characters. @@ -179,15 +180,15 @@ Lines can be shorter as well, down to 50 (or 25) characters. Justifying text to both the right and left can create uneven spacing ("[rivers of white]()"), which makes it hard to follow the flow of the text. -That's why Orbit [Text](/components/text/text/) components do not offer this as an alignment option. +That's why Orbit [Text](/components/text/text/) components don't offer this as an alignment option. Base the text alignment off the directionality of the language. -## Bidirectionality (RTL) +## Bi-directionality (RTL) Users of right-to-left (RTL) languages expect their content to start on the right side. This expectation sets the basis for all their interactions. If only the text starts on the right, -it will make it harder for users to understand what to do to accomplish their goals. +it makes it harder for users to understand what to do to accomplish their goals. Luckily, Orbit components are designed to work in both directions. This lets you mirror your layouts so the important aspects are clear to users of any language. @@ -203,12 +204,12 @@ are designed to work no matter the direction of the text, so the icons default to not reversing based on RTL settings (though you can manually override this). Focusing on making sure your designs make sense from each direction -helps ensure they will be usable by everyone. +helps ensure they are usable by everyone. ## Scale When designing across devices, window sizes, and orientations, -it can be difficult to maintain a consistent look that is usable at various scales. +it can be difficult to maintain a consistent look that's usable at various scales. It's important to ensure that people can use your designs however they access them. ### Media queries @@ -232,12 +233,12 @@ and make them small to make more room elsewhere. The problem, as anyone who's tried to hit the bullseye on a dartboard 🎯 knows, is that smaller targets are harder to hit. And when small targets are closer together, -it makes it more likely that users will hit the wrong target accidentally, +it makes it more likely that users hit the wrong target accidentally, increasing their frustration with your design. So especially in mobile designs, you want to make sure your targets are designed for human fingers. -This means aiming for sizes that are 7--10 mm wide. +This means aiming for sizes that are 7 to 10 mm wide. (Note that this involves the target size, which can include padding and isn't limited to only visible icons.) @@ -252,15 +253,15 @@ which you can see in the Orbit [design tokens for button margins](/foundation/de It's also important to keep in mind that the edges of screens aren't so easily accessible or may be used for swipe gestures, -so you'll want to add extra spacing for any targets near the edge. +so you want to add extra spacing for any targets near the edge. When you size and space your targets properly, you make your designs usable for people whose hands shake, older people, people with disabilities, people with large fingers, and more. And the great thing is that when you plan your designs like this on a mobile scale, -caling them up will help people with targeting on desktops. -This ensures your design will be usable in all situations. +scaling them up helps people with targeting on desktops. +This ensures your design are usable in all situations. ## Things to keep in mind while developing diff --git a/docs/src/documentation/02-foundation/03-border-radiuses.mdx b/docs/src/documentation/02-foundation/03-border-radiuses.mdx index 597d31562e..9e45051eef 100644 --- a/docs/src/documentation/02-foundation/03-border-radiuses.mdx +++ b/docs/src/documentation/02-foundation/03-border-radiuses.mdx @@ -10,4 +10,4 @@ because placing elements close to one another would cause a visual imbalance. The most common example is a group of form elements with small spacing between fields. It's clear at first sight that these fields would be less visually connected -with 6px border radiuses than with 3px ones. \ No newline at end of file +with 6px border radiuses than with 3px ones. diff --git a/docs/src/documentation/02-foundation/05-design-tokens.mdx b/docs/src/documentation/02-foundation/05-design-tokens.mdx index b0aa0708a0..cce739ae90 100644 --- a/docs/src/documentation/02-foundation/05-design-tokens.mdx +++ b/docs/src/documentation/02-foundation/05-design-tokens.mdx @@ -5,19 +5,19 @@ excerpt: Design tokens store visual design attributes. They help us make our UI import { Tips } from "@kiwicom/orbit-components/icons"; - +import DesignTokensList from "../../components/Placeholder"; + -We are preparing new specification of how we want theming work in Orbit. More soon. +We're preparing a new specification of how we want theming work in Orbit. More soon. - We use tokens instead of static values (like HEX codes) for color or sizing units. ## Installation -If you are already using `@kiwicom/orbit-components`, +If you're already using `@kiwicom/orbit-components`, you don't need to install the tokens because they're included as a dependency to ensure compatibility. You can install the package on its own. @@ -75,10 +75,10 @@ You can [download the tokens as XML](https://unpkg.com/@kiwicom/orbit-design-tok ## Formats -The main structure of the package is written in JavaScript for better usage in JavaScript projects. -We are also able to generate a JSON file, -which will allow us to transform this type of file into different ones. -It should be possible to transform JSON into SASS, LESS, Stylus, XML, and others. +The main structure of the package is written in JavaScript for better usage in JavaScript projects. +We're also able to generate a JSON file, +which enables us to transform this type of file into different ones. +It should be possible to transform JSON into SASS, LESS, Stylus, XML, and others. ## Naming conventions @@ -89,13 +89,11 @@ These conventions should be systematic and work according to the following templ }> - Every token name starts with its related CSS property, such as color, background, or fontSize. This should help in using them more naturally. - ## Full list of design tokens diff --git a/docs/src/documentation/02-foundation/06-elevation.mdx b/docs/src/documentation/02-foundation/06-elevation.mdx index 1cf7623be5..0ed2be67ef 100644 --- a/docs/src/documentation/02-foundation/06-elevation.mdx +++ b/docs/src/documentation/02-foundation/06-elevation.mdx @@ -4,6 +4,7 @@ excerpt: Use shadows to bring the content closer to the user on z-axis. --- import ElevationLevel from "../../components/ElevationLevel"; +import InlineToken from "../../components/Placeholder"; We have six main elevation levels: diff --git a/docs/src/documentation/02-foundation/07-icons/01-general.mdx b/docs/src/documentation/02-foundation/07-icons/01-general.mdx index bc1807dfad..5db6957050 100644 --- a/docs/src/documentation/02-foundation/07-icons/01-general.mdx +++ b/docs/src/documentation/02-foundation/07-icons/01-general.mdx @@ -2,6 +2,8 @@ title: General --- +import IconsList from "../../../components/Placeholder"; + ## Guidelines For guidelines on how to use the icons, see the [icon component](/components/visuals/icon/). @@ -18,11 +20,11 @@ or one of our icon colors: ### In Figma -All of our icons are included in our "[Orbit] Icons" Figma library (internal users only). +All of our icons are included in our "\[Orbit\] Icons" Figma library (internal users only). ### In React - + ### In mobile apps diff --git a/docs/src/documentation/02-foundation/07-icons/02-cdn.mdx b/docs/src/documentation/02-foundation/07-icons/02-cdn.mdx index 7f5737b939..0dc4fdc2a3 100644 --- a/docs/src/documentation/02-foundation/07-icons/02-cdn.mdx +++ b/docs/src/documentation/02-foundation/07-icons/02-cdn.mdx @@ -2,12 +2,17 @@ title: CDN --- + + You can download a PNG file for any Orbit icon at the following address: [https://images.kiwi.com/orbit-icons/{type}/{size}/{name}.png](https://images.kiwi.com/orbit-icons/success/32x32/airplane.png). + + Fill in the details as follows: - `{type}` is the style of the icon, represented through color. Choose one of the following: + - primary - secondary - tertiary @@ -16,9 +21,14 @@ Fill in the details as follows: - warning - error - white + - `{style}` can be either smaller (`32×32`) or larger (`48×48`). - `{name}` is the kebab-style name of the icon, which you can find in the [icon list](/foundation/icons/#list-of-icons). So for a success version in large of an airplane icon, you'd use the following address: + + [https://images.kiwi.com/orbit-icons/success/48×48/airplane.png](https://images.kiwi.com/orbit-icons/success/48x48/airplane.png) + + diff --git a/docs/src/documentation/02-foundation/08-illustrations.mdx b/docs/src/documentation/02-foundation/08-illustrations.mdx index a9c43ea1e0..56a4c3ea0c 100644 --- a/docs/src/documentation/02-foundation/08-illustrations.mdx +++ b/docs/src/documentation/02-foundation/08-illustrations.mdx @@ -3,6 +3,8 @@ title: Illustrations excerpt: Illustrations should support the overall message, not just be visual ornaments. --- +import IllustrationsList from "../../components/Placeholder"; + ## Sizes We have 4 sizes for use in our designs: @@ -20,16 +22,20 @@ Original illustrations are uploaded in 2200x1300px. ### In Figma If you want to insert an illustration into your Figma file, -you can find all illustrations in the "[Orbit] Illustrations" library. +you can find all illustrations in the "\[Orbit\] Illustrations" library. ### In React - + ### Standalone If you need to use the illustrations alone, -you can download them from one the lists below. +you can download them from one the lists below. ## List of illustrations diff --git a/docs/src/documentation/02-foundation/09-spacing.mdx b/docs/src/documentation/02-foundation/09-spacing.mdx index 7e3ba68e8a..9455998ab8 100644 --- a/docs/src/documentation/02-foundation/09-spacing.mdx +++ b/docs/src/documentation/02-foundation/09-spacing.mdx @@ -9,9 +9,9 @@ Our spacing is based on a 4-pixel grid, please use only these sizes: | --------- | ----- | ------------------------------------------------------------------------------ | | xx-small | `4` | Great for really small spaces such as connecting an error message to a form. | | x-small | `8` | Great to connect related components, like a header and a description. | -| small | `12` |   | +| small | `12` | | | medium | `16` | Great for inner padding, like left & right padding for content on mobile apps. | | large | `24` | Great for left & right inner padding in sections. | -| x-large | `32` |   | -| xx-large | `40` |   | +| x-large | `32` | | +| xx-large | `40` | | | xxx-large | `52` | Great for space between illustrations and headers. | diff --git a/docs/src/documentation/02-foundation/10-typography/01-general.mdx b/docs/src/documentation/02-foundation/10-typography/01-general.mdx index 727b77ba70..00b3f7a8c6 100644 --- a/docs/src/documentation/02-foundation/10-typography/01-general.mdx +++ b/docs/src/documentation/02-foundation/10-typography/01-general.mdx @@ -3,6 +3,8 @@ title: Colors excerpt: Typography is critical for communicating the hierarchy of a page. --- +import InlineToken from "../../../components/Placeholder"; + Always start by creating a clear hierarchy with the help of different sizes. Only work with font weight and body text color if you need to emphasize something. @@ -11,13 +13,13 @@ Only work with font weight and body text color if you need to emphasize somethin Headings are used to show the content hierarchy and are important for improving the reading experience for our users. -} /> + ### Colors To stand out from the page, we use as the only heading color. -### Font sizes +### Heading font sizes | Type | Size | | ------------------- | ------------------------------------------------------ | @@ -33,69 +35,62 @@ To stand out from the page, we use as the o - Try not to skip through heading levels. If you've used Title 1, the next level used, if intentionally smaller, should be Title 2. - + A display heading is great for when you need to show an important title at the top of more structured and content-heavy pages. - - When a heading requires the support of an icon, we recommend using the same color for both. It makes it easier to scan headings. - + It can work in very specific cases, but we usually don't combine Display and Level 1 headings on one page. - + The difference in the sizes of a Display heading and body text is too large. This difference causes a feeling of disconnect between pieces of information. -If you need to show a short description with your title, use Display Subtitle. +If you need to show a short description with your title, use Display Subtitle. - ## Text styles The most basic component for rendering text blocks. - -} /> + ### Colors for body text - + +### Text font sizes -### Font sizes - -|Size| Value| -|-|--| -|Small | | -|Normal | | -|Large | | +| Size | Value | +| ------ | ------------------------------------------ | +| Small | | +| Normal | | +| Large | | ### Basic guidelines for text styles - When you need something more important, scale it up with font size or color. When you need something less important, scale it down. @@ -103,7 +98,6 @@ When you need something less important, scale it down. - When you need to emphasize the description below a header, Large Primary does the job well. @@ -111,7 +105,6 @@ Large Primary does the job well. - If you need to highlight some text, use the bold weight of the same style. diff --git a/docs/src/documentation/02-foundation/10-typography/02-circular-pro.mdx b/docs/src/documentation/02-foundation/10-typography/02-circular-pro.mdx index 3ce7ef4508..0ad7e762b1 100644 --- a/docs/src/documentation/02-foundation/10-typography/02-circular-pro.mdx +++ b/docs/src/documentation/02-foundation/10-typography/02-circular-pro.mdx @@ -2,6 +2,8 @@ title: Circular Pro --- +import InlineToken from "../../../components/Placeholder"; + We use Circular Pro as the main typography supported by Orbit. Circular Pro is the only typeface for western texts and Lato is used for some eastern languages, with a fallback to system fonts. @@ -24,7 +26,7 @@ where we explain how to use Orbit with Roboto. In an ideal world, it should be that easy as changing the value of the design token -and everything would work automagically. +and everything would work automatically. It's actually not much harder, just a few more steps . ### In React components diff --git a/docs/src/documentation/03-components/08-visuals/seat/01-guidelines.mdx b/docs/src/documentation/03-components/08-visuals/seat/01-guidelines.mdx index 992439187f..6ada285911 100644 --- a/docs/src/documentation/03-components/08-visuals/seat/01-guidelines.mdx +++ b/docs/src/documentation/03-components/08-visuals/seat/01-guidelines.mdx @@ -54,4 +54,3 @@ Seat types present clear options for quick scanning. This allows users to find the option that fits them best. - diff --git a/docs/src/documentation/04-design-patterns/01-progressive-disclosure.mdx b/docs/src/documentation/04-design-patterns/01-progressive-disclosure.mdx index a85dd6943a..0e7ddf35d1 100644 --- a/docs/src/documentation/04-design-patterns/01-progressive-disclosure.mdx +++ b/docs/src/documentation/04-design-patterns/01-progressive-disclosure.mdx @@ -25,10 +25,10 @@ and explore [what components you can use](#how-to-use-with-orbit) in your own de Progressive disclosure is a way to manage the vast amount of information you have available. If you try to present all possible choices to users at once, -it will be difficult for them to choose what is important and what isn't. +it's difficult for them to choose what's important and what isn't. This leads to them getting **overwhelmed** by information (known as [information overload](https://en.wikipedia.org/wiki/Information_overload)) -and increases the chance that **they won't do anything**. +and increases the chance that **they don't do anything**. -At first sight, you can see the range that is being selected, but it is only after interacting with the slider that you'll see more details in the histogram. +At first sight, you can see the range that's being selected, +but it's only after interacting with the slider that you see more details in the histogram. ### Error forms @@ -109,7 +110,7 @@ This length is highlighted in the UI as a place where there are additional optio ![The text 'London' and 'Stay 3--5 nights', with the length of stay underlined and an edit button next to it.](../../images/design-patterns/NomadHoverLength.png) -If you select this, you'll find additional options for the length of stay. +If you select this, you see additional options for the length of stay. ![The same text as before, now with a slider underneath to select the length of stay from 1 to 60 nights.](../../images/design-patterns/NomadChangeLength.png) @@ -170,7 +171,7 @@ so it's best to hide it when it's not being used. [Tooltips](/components/overlay/tooltip/) highlight text to show that there is additional context available behind the text. -They are a basic way of keeping information present but hidden. +They're a basic way of keeping information present but hidden. You can see an example in the [pricing table](/components/structure/pricingtable/) below. The features are presented simply for comparison, diff --git a/docs/src/documentation/04-design-patterns/03-designing-forms.mdx b/docs/src/documentation/04-design-patterns/03-designing-forms.mdx index 79fad753a0..95476b21f8 100644 --- a/docs/src/documentation/04-design-patterns/03-designing-forms.mdx +++ b/docs/src/documentation/04-design-patterns/03-designing-forms.mdx @@ -13,7 +13,7 @@ It's makes it more clear for the user to complete fields one by one going down in a straight line rather than having to jump between columns, which might lead to their skipping some fields. Also, mobile devices make use of one-column layouts -as there is not enough space for multiple columns, +as there isn't enough space for multiple columns, so using one-column layouts helps us unify our mobile and desktop platforms. For more complicated forms, it's better to use a multi-column layout. @@ -81,7 +81,7 @@ We use inline validation, which is the best approach from our UX point of view. With this type of validation, we don't overload users with all messages at once, but only show the first error message in the form. The other messages are hidden but marked with a red exclamation mark. -In this way, users can see that there is an error -and will see the message after they focus on the corresponding field. +In this way, users see that there is an error +and also see the message after they focus on the corresponding field. This approach should be used across all forms we design. You can find more information about validation in the coming article about forms and errors. diff --git a/docs/src/documentation/05-development/01-guides/01-developing-layouts.mdx b/docs/src/documentation/05-development/01-guides/01-developing-layouts.mdx index 730f5519a8..e3fd29461a 100644 --- a/docs/src/documentation/05-development/01-guides/01-developing-layouts.mdx +++ b/docs/src/documentation/05-development/01-guides/01-developing-layouts.mdx @@ -68,8 +68,8 @@ there are two components that offer consistent **spacing** for groups of compone Stacks work when you want to focus on a group of components laid out in a single direction. The direction can be either horizontal or vertical -and there are lots of options for how the components will fit into the space. -In all cases, there will be consistent spacing in a single direction. +and there are lots of options for the components to fit into the space. +In all cases, there is consistent spacing in a single direction. Inline components give you consistent spacing both horizontally and vertically. They work for sets of components that might span multiple lines. diff --git a/docs/src/documentation/05-development/01-guides/02-dictionary.mdx b/docs/src/documentation/05-development/01-guides/02-dictionary.mdx index 0f3740449d..239e1bcb76 100644 --- a/docs/src/documentation/05-development/01-guides/02-dictionary.mdx +++ b/docs/src/documentation/05-development/01-guides/02-dictionary.mdx @@ -38,7 +38,7 @@ and useTranslate hooks for your functional components. - If a translation key doesn't exist in your language, the fallback is `en_GB`, which is our default language. - If a translation key doesn't exist in either file (your language, the default language), - the translation key will be rendered (for example, `button_close`). + the translation key is rendered (for example, `button_close`). ## Your own dictionary @@ -61,8 +61,8 @@ const App = () => ( ## Languages -We store all inner strings we translate inside of our Github repository -and export them to NPM. +We store all inner strings we translate inside of our GitHub repository +and export them to npm. + ## Favicons + + ## Brand color These are the basic palette colors. @@ -203,7 +207,7 @@ is to use Pantone or CMYK. | Color type | Value | | ------------- | --------------------------------- | -| Pantone color | **PANTONE 3275** | +| Pantone color | **Pantone 3275** | | RAL color | **RAL 170 60 40** (Persian green) | | CMYK color | **CMYK(93,0,57,0)** | diff --git a/docs/src/documentation/06-kiwi-use/01-brand/brand-guidelines/02-code-kiwi-com.mdx b/docs/src/documentation/06-kiwi-use/01-brand/brand-guidelines/02-code-kiwi-com.mdx index ff732f8003..73e41f9776 100644 --- a/docs/src/documentation/06-kiwi-use/01-brand/brand-guidelines/02-code-kiwi-com.mdx +++ b/docs/src/documentation/06-kiwi-use/01-brand/brand-guidelines/02-code-kiwi-com.mdx @@ -4,7 +4,7 @@ title: code.kiwi.com code.kiwi.com is the brand of the community of people who code and design [code.kiwi.com](https://kiwi.com/). -We organise events and speak at conferences. +We organize events and speak at conferences. On our [blog](https://code.kiwi.com/), we also write about the things we get up to and the technologies we use. @@ -142,17 +142,9 @@ Basic brand resources if you need to promote the code.kiwi.com community. ## Social links - + - + -We write **clearly** and **concisely** so people will understand what we mean. +We write **clearly** and **concisely** so people understand what we mean. ### [Passionate](/kiwi-use/content/voice-and-tone/passionate) @@ -41,7 +41,7 @@ We treat everyone with **respect** and **without prejudice**. -We are open about our **ups and downs** and everything in between. +We're open about our **ups and downs** and everything in between. ## Tone @@ -64,7 +64,7 @@ This doesn't mean we aren't passionate, it just means **we know when and how** to show that passion**.** Similarly, when our resources are stressed such as during major travel disruptions, -we know our customers want to know what is happening and how they can get home. +we know our customers want to know what's happening and how they can get home. At such times, our transparency becomes the most important. We still want to show empathy (and we're not afraid to say "sorry"), diff --git a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/02-empathetic.mdx b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/02-empathetic.mdx index 80018355c1..87d08bd0ca 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/02-empathetic.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/02-empathetic.mdx @@ -23,18 +23,18 @@ and how we can move closer to an ideal state. -You should always know **who you are writing for** +You should always know **who you're writing for** and adjust your language and style based on it. Your [writing should also be inclusive](/kiwi-use/content/voice-and-tone/inclusive/) so your entire audience is a part of it, no matter their background or language level. -### Use terms your audience will understand +### Use terms your audience understands - While we have a glossary for terms we use, - we shouldn't expecteveryone to be intimately familiar with it. + we shouldn't expect everyone to be intimately familiar with it. We want to use **general terms** as much as possible. - Keep **jargon** and **technical** terms **only** for those who know it well. -- Write in plain language so people with any literacy level will understand. +- Write in plain language so people with any literacy level understand. @@ -63,14 +63,14 @@ If it flows naturally when you say it aloud, people can better understand it. Tone down the formality (when it makes sense) to keep a **conversational style**, including using contractions. -This will have the side effect of [making things shorter](/kiwi-use/content/voice-and-tone/straightforward/#be-concise). +This has the side effect of [making things shorter](/kiwi-use/content/voice-and-tone/straightforward/#be-concise). - To get a quick answer (to your request) -- So you'll need to give us more details about it. +- So you need to give us more details about it. - We can't start now. @@ -165,7 +165,7 @@ Keep your text focused on your audience. ### Describe what choices mean for users When describing a potential service or other option, -make it clear what choosing that option will mean **for users** up front. +make it clear what choosing that option means **for users** up front. Don't wait until after they've chosen to see what it means. Understand **what users expect** at each step in the process and you can help satisfy them. diff --git a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/03-straightforward.mdx b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/03-straightforward.mdx index 0aeeac4c2f..7052ec2876 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/03-straightforward.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/03-straightforward.mdx @@ -15,7 +15,7 @@ We don't want to hide the main ideas inside a lot of fluff. If there is a potential problem, state it **directly**. If you have a potential solution, **bring it up**. -We are busy traveling, planning our next trip, +We're busy traveling, planning our next trip, or designing the perfect travel experience. We don't have time to wait for someone to get to the point. @@ -37,6 +37,8 @@ It's fine to use contractions like "it's" as long as it's clear what you mean. Avoid general terms like "stuff" to substitute for actually explaining what you're talking about. + + @@ -57,6 +59,8 @@ Avoid general terms like "stuff" to substitute for actually explaining what you' + + ### Structure what you write [Studies have shown](https://www.nngroup.com/articles/how-people-read-online/) @@ -122,8 +126,8 @@ This includes writing copy that describes the relevance and importance of variou Don't take too much time or space to explain your point -or you will **lose your audience**. -Especially online, [people will only scan your text](https://www.nngroup.com/articles/how-people-read-online/)--- +or you **lose your audience**. +Especially online, [people only scan your text](https://www.nngroup.com/articles/how-people-read-online/)--- they don't want to waste time or effort. Keep things **short**. diff --git a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/05-inclusive.mdx b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/05-inclusive.mdx index 81b5dca052..35f2125766 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/05-inclusive.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/05-inclusive.mdx @@ -50,6 +50,8 @@ Write using more **universal language**. Slang can be harder for people with English as a second language to understand. + + @@ -68,11 +70,13 @@ Slang can be harder for people with English as a second language to understand. + + ## Be inclusive -We write so everyone feels a part of what we are saying. +We write so everyone feels a part of what we're saying. Make sure your writing includes everyone in its defaults. ### Use gender-neutral language @@ -85,7 +89,7 @@ Feel free to use "they" in the singular for people of unknown gender. -- After users log in, they'll see a welcome screen. +- After users log in, they see a welcome screen. - Everyone, come and join the fun! - flight attendant @@ -93,7 +97,7 @@ Feel free to use "they" in the singular for people of unknown gender. -- After the user logs in, he'll see a welcome screen +- After the user logs in, he sees a welcome screen - Guys, come and join the fun! - steward/stewardess @@ -131,7 +135,7 @@ Make exceptions for groups who prefer identity-first descriptions. Make sure everything you write is [accessible](/foundation/accessibility/) to everyone. -Remember that **not everyone will see** your visual content, +Remember that **not everyone sees** your visual content, so communicate the message in **various ways**. - Include various **fallbacks** for your content. diff --git a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/06-transparent.mdx b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/06-transparent.mdx index f06677067e..5874ff62ce 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/06-transparent.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/01-voice-and-tone/06-transparent.mdx @@ -7,23 +7,23 @@ import { AlertCircle, Anywhere, InformationCircle } from "@kiwicom/orbit-compone -We are open about as many things as possible. +We're open about as many things as possible. We work to **build trust** to create productive, long-lasting relationships. This means being open about our decisions and the factors that influence them. -We do not share **anything** that users have shared with us in confidence. +We don't share **anything** that users have shared with us in confidence. Sharing private user information violates the trust that we want to develop. We share what we do, including [our open source software](https://github.com/kiwicom), and why we do it. -We do not share private data. +We don't share private data. ## Be public by default When there's space, share the reasons for decisions and options. -When there are problems, clearly communicate how we are working to fix them. +When there are problems, clearly communicate how we're working to fix them. ## Make consequences clear diff --git a/docs/src/documentation/06-kiwi-use/02-content/02-grammar-and-mechanics.mdx b/docs/src/documentation/06-kiwi-use/02-content/02-grammar-and-mechanics.mdx index 696d5d3a97..310824b7dc 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/02-grammar-and-mechanics.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/02-grammar-and-mechanics.mdx @@ -5,11 +5,15 @@ excerpt: Basic grammar guidelines for writing with Orbit. ## Why should we care? + + > If language is not correct, then what is said is not what is meant; > if what is said is not what is meant, > then what must be done remains undone. > -> Confucious +> Confucius + + The guidelines here are intended to free you from having to spend time worrying about details like spelling. @@ -19,6 +23,8 @@ You can spend that time focusing on getting the important part of your content r The main language of Orbit and Kiwi.com is American English. + + @@ -39,15 +45,17 @@ The main language of Orbit and Kiwi.com is American English. -Always include diacritics if they are there: + + +Always include diacritics if they're there: Oliver Dlouhý, Petra Vaškových. ## Punctuation -Prefer em dashes (---) over semicolons---never use hyphens unless you are hyphenating. +Prefer em dashes (---) over semicolons---never use hyphens unless you're hyphenating. Use en dashes to connect things, such as times and dates, in short forms: -Jan 24--Feb 28, 10:00--14:00. +Jan 24 to Feb 28, 10:00 to 14:00. Don't use punctuation in abbreviations: UK, US. @@ -81,6 +89,8 @@ If you can't, write as if the plural option included both the singular and the p If it's important to write specifically that there may be one or multiple items, use the phrase "one or more". + + @@ -101,6 +111,8 @@ use the phrase "one or more". + + ## Numbers Generally, one to nine are written as words. @@ -117,7 +129,7 @@ Write the numbers one to nine as numerals in these cases: When talking about numerous people or animals, always write thousands, millions, or billions in full: 60.5 million passengers. -For anything else, m or bn is ok, depending on how it reads: \$60bn. +For anything else, M or B is ok, depending on how it reads: $60B. Use commas to separate thousand units: 1,000. @@ -138,30 +150,34 @@ use BCE (Before Common Era) and CE (Common Era). The plural of euro is euro. -€, \$ and £ are placed before the price, without a space: €6.43. +€, $ and £ are placed before the price, without a space: €6.43. Kč is placed after the price. ¢ and p are placed after the price without a space: 83¢. + + - euro -- €10, \$15, £20 +- €10, $15, £20 - euros -- 10 €, \$ 15, 20 £ +- 10 €, $ 15, 20 £ + + ## Lists When presenting a sequence of steps, use an ordered list. @@ -191,11 +207,11 @@ Brno offers many attractions: Write short sentences. Short sentences improve readability. -They are more powerful. +They're more powerful. Long sentences that run on and on, -and are full of commas, colons and semicolons---and many different clauses---are really confusing +and are full of commas, colons, and semicolons---and many different clauses---are really confusing and awkward to read for even the strongest readers---just look at James Joyce's Ulysses; -it's an impossible read that most people just cannot get through +it's an impossible read that most people just can't get through because they can't follow anything because his sentences are so long and winding, like the narrow streets of Dublin. diff --git a/docs/src/documentation/06-kiwi-use/02-content/03-glossary.mdx b/docs/src/documentation/06-kiwi-use/02-content/03-glossary.mdx index c0a5afc6ab..5cec7f2b74 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/03-glossary.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/03-glossary.mdx @@ -24,7 +24,7 @@ radius search e-ticket -: Contains travel details and enables check-in but does not allow a passenger to board. +: Contains travel details and enables check-in but doen't allow a passenger to board. boarding pass @@ -68,9 +68,9 @@ such as a camera bag or purse. Passenger Name Record (PNR) : A numbering convention used in the travel industry. -Each itinerary will have a unique PNR associated with all the booking and personal details. +Each itinerary has a unique PNR associated with all the booking and personal details. -booking ID +booking ID (BID) : Kiwi.com's private numbering convention used to locate our bookings (such as 2326340). Always use the long form (not BID) in communications with users. @@ -84,7 +84,7 @@ segment : A segment is an atomic unit of the itinerary. One segment connects two locations and can be traveled by different vehicles. If you're taking a flight, it's called a **flight segment**. -When you're traveling by bus, it is a **bus segment**. And so on. +When you're traveling by bus, it's a **bus segment**. And so on. connection @@ -109,7 +109,7 @@ and the second (called the **inbound sector**) is from Beijing to Barcelona. A multi-city trip has two or more sectors. For example, a multi-city trip that goes from Prague to London, then from Manchester to Barcelona, -and then from Madrid to Vienna will have three sectors. +and then from Madrid to Vienna has three sectors. itinerary @@ -158,7 +158,7 @@ Cardholder's name Kiwi.com : This is the brand name of our product. -It is not Kiwi or Skypicker. +It's not Kiwi or Skypicker. Kiwi.com Guarantee diff --git a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/01-tone-of-voice.mdx b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/01-tone-of-voice.mdx index afff8e9582..33e0a5a3e7 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/01-tone-of-voice.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/01-tone-of-voice.mdx @@ -2,8 +2,6 @@ title: Tone of voice --- -[broken link](https://collier.cz/this-is-broken) - Through the way we speak, we want to ignite people's passion to travel and tap into their thirst for discovery. Whatever the message on social media, @@ -11,7 +9,7 @@ whether it's inspirational, supportive, or reactive, we want to inspire them to adventure further in the knowledge that Kiwi.com will get them there. We need to convey a new approach to traveling for a new world and get our customers to -> **SEE THE WORLD DIFFERENTLY.** +> **See the world differently.** See how this works with our [core principles](/kiwi-use/content/voice-and-tone/). @@ -24,7 +22,7 @@ See how this works with our [core principles](/kiwi-use/content/voice-and-tone/) We love what we do so we write with feeling because we share in our customers' excitement. Writing to inspire and bring out their adventurous side. Life is about living and our copy should reflect that. -We are about **_can_** and **_should_**---make them feel like they want to go and pack their bags. +We're about **_can_** and **_should_**: make them feel like they want to go and pack their bags. ## **Empathetic** @@ -58,7 +56,7 @@ We write to make customers feel part of the conversation, regardless of their cu We're always simplifying. Don't use 5 words where 2 will do. We don't speak in a corporate way, but we're always professional. -We're to the point -- clear and concise with our actions. +We're to the point: clear and concise with our actions. ## Transparent @@ -74,15 +72,15 @@ We use conversational and clear language to make our point. ### Spring - + #### Be less... + ![Spring is coming. Where are you going?](../../../../../images/social-media/spring-dont.png "Lacks passion and excitement. Feels functional and formal.") - - + #### Be more... - + ![It's spring! Are your bags packed? You could be on a beach, a trail, or a cobbled city street -- @@ -90,38 +88,34 @@ just follow the sun](../../../../../images/social-media/spring-do.png "Passionat ### Restrictions - - + #### Be less... - + ![We'll inform you about travel restrictions on your route while searching for your next trip at Kiwi.com](../../../../../images/social-media/restrictions-dont.png "Cold. Corporate.") - - + #### Be more... - + ![Relax. Whatever route you're taking on your adventure, -we'll let you know about any travel restructions while you're searching on Kiwi.com +we'll let you know about any travel restrictions while you're searching on Kiwi.com ](../../../../../images/social-media/restrictions-do.png "Inclusive and transparent.") ### Stopovers - - + #### Be less... - + ![This filter lets you exclude stopover destinations you find difficult or inconvenient to travel through.](../../../../../images/social-media/stopover-dont.png "Functional. Lacks empathy.") - - + #### Be more... - + ![Not the stopover you want? That’s okay, our smart little filter lets you pick and choose your route – it’s that simple. @@ -129,35 +123,31 @@ That’s okay, our smart little filter lets you pick and choose your route – i ### Behind the scenes - - + #### Be less... - + ![Let's take a look behind the scenes at the people and processes that make our business what it is.](../../../../../images/social-media/behind-scenes-dont.png "Cold. Corporate.") - - + #### Be more... - + ![Ever wondered what goes on behind the scenes to get you to the places you’ve dream of? Come on in and we’ll show you.](../../../../../images/social-media/behind-scenes-do.png "Inclusive and transparent.") ### Options - - + #### Be less... - + ![Check out routes by check-in options](../../../../../images/social-media/options-dont.png "Functional. Unclear.") - - + #### Be more... - + ![Dreaming of a beach and just flip flops? You can search trips based on how much or how little luggage you want to take? @@ -165,18 +155,16 @@ You can search trips based on how much or how little luggage you want to take? ### At the airport - - + #### Be less... - + ![Here's a beginner's guide to a crucial part of the airport experience. ](../../../../../images/social-media/airport-dont.png "Cold. Corporate.") - - + #### Be more... - + ![The start of any adventure is how you get there. So, here’s some tips for a stress-free trip through any airport @@ -185,7 +173,7 @@ So, here’s some tips for a stress-free trip through any airport ## In short: Guiding principles 1. **Always professional**: - we know what we are doing, and our credibility comes naturally + we know what we're doing, and our credibility comes naturally 2. **Globally inclusive**: we include different cultures and avoid issues that could be lost in translation diff --git a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/02-visual-treatment.mdx b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/02-visual-treatment.mdx index b56584f980..7c13653949 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/02-visual-treatment.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/social-media/02-visual-treatment.mdx @@ -15,17 +15,16 @@ Our photography should always have a sense of optimism. The subjects and environments should feel authentic. We shouldn't be afraid of showing **real faces and emotions.** People should be **unposed** and their **composition** within the environment **natural**. -Lighting, color and tone should be **unfiltered and realistic \#NoFilter!** +Lighting, color, and tone should be **unfiltered and realistic \#NoFilter!** Each image should establish an emotional connection with our audience, showing them the world Kiwi.com can offer. - - + ## Our destinations... - + -**ARE** real, authentic and full of wanderlust. +**are** real, authentic and full of wanderlust. Images don't just show the place but the _details_ of the people and the story. @@ -56,7 +55,7 @@ Images don't just show the place but the _details_ of the people and the story. -**ARE NOT** unrealistic, over edited, broad stock landscapes that lack emotion. +**are not** unrealistic, over edited, broad stock landscapes that lack emotion. @@ -80,12 +79,11 @@ Images don't just show the place but the _details_ of the people and the story. - - + ## Our people... - + -**ARE** diverse and show real authentic moments. +**are** diverse and show real authentic moments. They are natural, capturing the emotions and adventurous spirit of our audience. @@ -110,7 +108,7 @@ They are natural, capturing the emotions and adventurous spirit of our audience. -**ARE NOT** posed, facing away from the camera or recreating unrealistic and cliched moments. +**are not** posed, facing away from the camera or recreating unrealistic and cliched moments. @@ -134,10 +132,9 @@ They are natural, capturing the emotions and adventurous spirit of our audience. - - + ## Our travel... - + **IS** bright and cheerful. It's packing and getting ready. @@ -196,12 +193,11 @@ or suggestive or monotony/complexity/delays. - - + ## Our moving images... - + -**ARE** authentic and help create awe in the world around you to tell a more engaging story. +**are** authentic and help create awe in the world around you to tell a more engaging story. @@ -233,7 +229,7 @@ or suggestive or monotony/complexity/delays. -**ARE NOT** stylized, tongue-in-cheek or over-produced, +**are not** stylized, tongue-in-cheek or over-produced, or trying to represent unreal situations. diff --git a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/01-principles.mdx b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/01-principles.mdx index f8210b90e1..f4a6e42896 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/01-principles.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/01-principles.mdx @@ -10,7 +10,7 @@ Not to point out problems or make you feel bad for not meeting some standard. The idea is to **free** you from having to worry about details so you can create **helpful** documentation. Instead of spending time agonizing over April 1 vs. -1 April, you can **focus on writing** something people will read and use. +1 April, you can **focus on writing** something people read and use. If you find the guidelines too constraining or you're missing guidance on something particular, @@ -19,7 +19,7 @@ Kiwis can reach us at [\#plz-documentation](https://skypicker.slack.com/archives ## Why write docs -We write documentation so that what we create will actually be **used**. +We write documentation so that what we create is actually be **used**. For your project to be used, people have to know: @@ -33,17 +33,17 @@ One thing to keep in mind is that the person who may need to know how your proje could be **you** in six months. After you leave a project, you might not remember all of the decisions you made and why you made them. -Having clear documentation will help make sure you don't lose your valuable insights to time. +Having clear documentation helps make sure you don't lose your valuable insights to time. ## Audiences It's always important to keep in mind **who** you're writing **for**. -Each reader will have specific **expectations** and **context** when reading your docs. +Each reader has specific **expectations** and **context** when reading your docs. Some examples of possible audiences and their expectations: - External users - - Will have very little context + - Have very little context - May need more information - Developers - Probably want technical information @@ -57,11 +57,11 @@ Before you start writing, you want to ask yourself questions about your readers - Are they **new** to this project area? Do they have **experience** with it? -- **Why** will they be reading? +- **Why** are they reading? To accomplish a **task**? **To learn** about the project? - Will this document come in the middle of something they're in a **hurry** to finish? How are they likely to be **feeling** when starting to read? -The answers to these questions will give you a better idea of how to present your information. -You'll have a good idea of how to structure your document. +The answers to these questions give you a better idea of how to present your information. +Then you get a good idea of how to structure your document. diff --git a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/02-tone.mdx b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/02-tone.mdx index 4aa13e8921..d0d5a0e0ae 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/02-tone.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/02-tone.mdx @@ -3,16 +3,16 @@ title: Tone --- At Kiwi.com, we speak with one voice. -That voice is a [blend of our core principles](/for-kiwi/content/voice-and-tone/). +That voice is a [blend of our core principles](/kiwi-use/content/voice-and-tone/). When producing technical content, -usually the most important principle will be that we are [straightforward](/kiwi-use/content/voice-and-tone/straightforward/). -It is important for our technical writing to be clear and understandable. +usually the most important principle is that we are [straightforward](/kiwi-use/content/voice-and-tone/straightforward/). +It's important for our technical writing to be clear and understandable. At the same time, our other principles are still important. Our [empathy](/kiwi-use/content/voice-and-tone/empathetic/) can be seen in how we [think of our audience while writing](/kiwi-use/content/specific-areas/technical-content/#audiences). -We are also still [passionate](/kiwi-use/content/voice-and-tone/passionate/)---even in technical writing. +We're also still [passionate](/kiwi-use/content/voice-and-tone/passionate/), even in technical writing. This means there can be specific times when some **emotion** and **personality** makes sense in technical writing. diff --git a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/03-structure.mdx b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/03-structure.mdx index 73dc84f34e..858e8adaab 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/03-structure.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/03-structure.mdx @@ -13,14 +13,14 @@ They all focus on different things: Each of these types has different goals. To decide which to write, -it helps to [know who you are writing for](/kiwi-use/content/specific-areas/technical-content/#audiences). +it helps to [know who you're writing for](/kiwi-use/content/specific-areas/technical-content/#audiences). For each type, you want to pick a specific topic with a specific goal and write **only about that topic**. Use links to give people access to additional context and related topics. When you know the specific topic, -give it a **short** title to make it clear what the document will contain. +give it a **short** title to make it clear what the document contains. For most types, the title should emphasize the action ("Making a reservation", "Deploying your app to Kubernetes"). @@ -40,7 +40,7 @@ Always include **clear headings** to structure your document into clear sections The introduction should include **why** the given product or service is **important**. Then the tutorial should guide the reader through an ordered **series of steps** -that will teach them the basics of how to accomplish something. +that teaches them the basics of how to accomplish something. ## How-to guides @@ -48,7 +48,7 @@ The introduction should make it clear **what** users can **accomplish** with the **and why** they'd want to do so. The guide should continue with clear, **ordered steps** for accomplishing the task. -Put any information that is not immediately useful to accomplishing the task **elsewhere**, +Put any information that's not immediately useful to accomplishing the task **elsewhere**, such as in a reference guide, and **add a link** to it.. ## Reference guides @@ -56,7 +56,7 @@ such as in a reference guide, and **add a link** to it.. The introduction should explain **what** information is **included** in the guide and **why** it might be **useful**. -The rest of the guide should be information that is **clearly structured** +The rest of the guide should be information that's **clearly structured** without many details on why or how to accomplish something. Include links to specific how-to guides when relevant. diff --git a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/04-language.mdx b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/04-language.mdx index 0ecbee1bfa..2300b2cb8e 100644 --- a/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/04-language.mdx +++ b/docs/src/documentation/06-kiwi-use/02-content/04-specific-areas/technical-content/04-language.mdx @@ -14,6 +14,8 @@ Be clear and to the point. Unless there is a very good reason to do so, avoid using "we" and "our". + + @@ -34,14 +36,18 @@ Unless there is a very good reason to do so, avoid using "we" and "our". + + ## Tenses -In most [types of documentation](/kiwi-use/content/specific-areas/technical-content/structure/), -especially in how-to guides, readers will be following the instructions as they read. +For most [types of documentation](/kiwi-use/content/specific-areas/technical-content/structure/), +especially in how-to guides, readers are following the instructions as they read. Use the present tense to describe actions. Similarly, avoid "would" and "could" (and any other modals expressing uncertainty) in conditional statements. + + @@ -62,6 +68,8 @@ Similarly, avoid "would" and "could" + + ## Creating links When inserting links into the text, @@ -69,7 +77,7 @@ try to give them descriptive text (not just the URL). Make exceptions for API endpoints when the purpose of including the link is to show the location of the endpoint. -Also avoid phrases such as "click here". +Also avoid phrases such as "click here." Have the text make sense out of context---when you're looking just at the link text. @@ -109,7 +117,7 @@ and attribute as few human qualities to them as possible. - The server tells the client when it's received the request. - The app sees when you've entered the airport. -- If you format the request badly, the server will refuse to accept it. +- If you format the request badly, the server refuses to accept it. @@ -119,13 +127,13 @@ and attribute as few human qualities to them as possible. Always be specific about what you're referring to. If you introduce a specific product in the first sentence of a section, -don't assume the reader will know what you mean by "it" two paragraphs +don't assume the reader knows what you mean by "it" two paragraphs (or even two sentences later). -Repeat your references to make it clear what you are talking about. +Repeat your references to make it clear what you're talking about. Any time you have long strings of nouns, break them up into smaller pieces -o it's clear what refers to what. +so it's clear what refers to what. @@ -154,7 +162,7 @@ They make it clear what steps need to be done when. Don't weaken this guidance by numbering other things where the order doesn't matter. For example, headings in an article should follow a clear semantic structure. -That structure should be enough, so the headings should not be numbered. +That structure should be enough, so the headings shouldn't be numbered. ## Use contractions @@ -166,6 +174,8 @@ It's best to avoid shortening noun and verb combinations where it might be confu (such as making readers think something is a possessive rather than a noun and verb). But common contractions such as _it's_ should be clear (just don't confuse _it's_ and _its_). + + @@ -187,3 +197,5 @@ But common contractions such as _it's_ should be clear (just don't confuse _it's + + diff --git a/docs/src/documentation/06-kiwi-use/03-guides/01-bizdev.mdx b/docs/src/documentation/06-kiwi-use/03-guides/01-bizdev.mdx index 80a3af43d7..d003c56a38 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/01-bizdev.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/01-bizdev.mdx @@ -1,21 +1,19 @@ --- -title: Biz dev assets +title: Biz Dev assets excerpt: Lists of assets created for GoodData reports by Biz Dev. --- -import ImagesDownloadList from "../../../components/ImagesDownloadList" +import ImagesDownloadList from "../../../components/ImagesDownloadList"; ## Icons -The icons listed below are not part of the global Orbit icon set +The icons listed below aren't part of the global Orbit icon set but are in the same style as all other icons. Please, **use these icons only for GoodData or other Biz Dev reports**. -These icons are not supposed to be used in any product. +These icons aren't supposed to be used in any product. - - ## Headers diff --git a/docs/src/documentation/06-kiwi-use/03-guides/02-preparing-carrier-logos.mdx b/docs/src/documentation/06-kiwi-use/03-guides/02-preparing-carrier-logos.mdx index fe0888d181..3354d48e8a 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/02-preparing-carrier-logos.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/02-preparing-carrier-logos.mdx @@ -1,29 +1,29 @@ --- title: Preparing carrier logos -exceprt: Guidelines for preparing carrier logo in high quality. +excerpt: Guidelines for preparing carrier logo in high quality. --- -Almost every airline, bus or train carrier has its own logo and colors. -For some of them, the brand is important for its recognizability, +Almost every airline, bus, or train carrier has its own logo and colors. +For some of them, the brand is important for being recognizable, while others are less known. For us, logos matter. -**tl;dr**: Here is the [PSD (Photoshop) template](/carrier-logo-template.psd) you may be looking for. +**tl;dr**: Here is the [Photoshop template](/carrier-logo-template.psd) you may be looking for. ## People ❤️ brands Travelers are especially interested in travel brands. -That's the main reason why we carefully prepare logos for those carriers that appear on -Kiwi.com -- to **help people quickly realize who they'll travel with**. +That's the main reason we carefully prepare logos for those carriers that appear on +Kiwi.com---to **help people quickly realize who they're traveling with**. How many of these logos are you able to identify just from this screenshot? Two? Three? Are you a seasoned traveler from Europe? Maybe you recognize all of them. -![Eight different carrier logos](../../../images/carrier-logos/logo-carriers.png "1st row: Ryanair, KLM, Regiojet, Flixbus; +![Eight different carrier logos](../../../images/carrier-logos/logo-carriers.png "1st row: Ryanair, KLM, RegioJet, FlixBus; 2nd row: Tap Portugal, Vueling, Lufthansa, easyJet") We believe that **it's not enough to just mention the brand name in some small text in the caption**. -We want to provide information that will help people quickly recognize their favorite airlines. +We want to provide information that helps people quickly recognize their favorite airlines. Using well-crafted logos helps us achieve this (and it looks great too 🥳). ## Having a nice logo isn't rocket science @@ -49,7 +49,7 @@ An image is worth thousands words: ](../../../images/carrier-logos/carrier-logo-template.png) To make it even easier, we've prepared a [Photoshop template](/carrier-logo-template.psd) for you. -You just need to save your logo as PNG and upload it to Nest 🙂 +You just need to save your logo as a PNG and upload it to Nest 🙂 ### 2) Use a solid color for the background @@ -75,5 +75,5 @@ Orbit takes care of all UI styling, so there's **no need for round corners or transparent background**. Just create a logo according to our guidelines above and upload it to Nest. -Automatic resizing and Orbit will handle the rest. +Automatic resizing and Orbit handle the rest. Sounds good, right? 🙂 diff --git a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/01-basics.mdx b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/01-basics.mdx index 544bc99eaa..e27326fd43 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/01-basics.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/01-basics.mdx @@ -14,13 +14,13 @@ Instead of different tools in different domains, everyone can take advantage of a unified process to focus on creating the best experiences. All of it is focused on the principle of designing **first for** [**native mobile** implementations](https://www.figma.com/file/PWGp3tANcQDVGI1W12swfn/Mobile-Experience-Guidelines?node-id=0%3A1). -From this seed, all of the other designs will grow. +From this seed, all of the other designs grow. We've broken the process down into various parts so you can focus on what you need to know. Get started by logging into Figma and finding your team. If you run into any issues, -the slack channel \#plz-figma is your one-stop answer shop. +the slack channel #plz-figma is your one-stop answer shop. ## **Logging in** @@ -30,8 +30,8 @@ The easiest way is to click the Figma logo from the Okta dashboard. ![GATSBY_EMPTY_ALT](../../../../images/working-with-figma/Okta.png) If you don't see the logo, -you can request access in [\#plz-access](https://skypicker.slack.com/archives/C2751M4TZ) -and tag **\@will**. +you can request access in [#plz-access](https://skypicker.slack.com/archives/C2751M4TZ) +and tag **@will**. You can also log in directly with Figma. @@ -51,7 +51,7 @@ Now you need to find the designs relevant to you. ## **Joining teams** If you've never logged into Figma before, -you'll find an overview of the teams available to you +you see an overview of the teams available to you within the [Kiwi.com organization](/kiwi-use/guides/working-with-figma/structure/#organization). ![GATSBY_EMPTY_ALT](../../../../images/working-with-figma/KiwiOrgOverview.png) @@ -92,7 +92,7 @@ our responsive designs for viewing the website on mobile devices? Also, the separate teams for the app and website mean we only have to load the relevant components. - This will ensure the files load quickly and you can get to work on the relevant designs. + This ensures the files load quickly and you can get to work on the relevant designs. #### **Linking designs** diff --git a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/02-structure.mdx b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/02-structure.mdx index d323403895..e463c94c15 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/02-structure.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/02-structure.mdx @@ -20,35 +20,35 @@ as you can see in our [demo team](https://www.figma.com/file/T32gf6jCzHNhwOh0LZG ### Organization The Kiwi.com organization is already set up for you and should contain everything you need. -If you have any questions about the settings or organization, use the [\#plz-figma Slack channel](https://skypicker.slack.com/archives/CRU8S2WP4). +If you have any questions about the settings or organization, use the [#plz-figma Slack channel](https://skypicker.slack.com/archives/CRU8S2WP4). ### Teams All teams are already set up for you (including [separate mobile and desktop teams](/kiwi-use/guides/working-with-figma/#why-are-mobile-and-desktop-split-into-two-teams)) and all you have to do is join. -**CS Systems** +**CS Systems** All designs files related to our customer support and Balkan -**Demo Team** +**Demo Team** Used to demonstrate project and file organization within Figma. -**Kiwi.com App** +**Kiwi.com App** Design files for native apps. -**Kiwi.com Web** +**Kiwi.com Web** Design files for Kiwi.com website. Including both responsive and desktop designs. -**Messaging** +**Messaging** Everything related to user messaging like e-mails, Facebook Messenger, etc. -**Orbit** +**Orbit** Everything related to our design system, from UI kit to assets for orbit.kiwi documentation. -**Service Design** +**Service Design** Mapping customer journeys and service blueprints. -**Tequila** +**Tequila** Design files for our B2B platform Tequila. ### Projects @@ -89,8 +89,8 @@ Each library file has a responsible maintainer (such as \@henne for the Booking Each team has a specific project for explorations. This is a good place to try out new concepts and see which ideas work. -Keeping explorations separate like this will ensure -that your core Figma files won't grow in size over time +Keeping explorations separate like this ensures +that your core Figma files doen't grow in size over time and that you can clearly separate the discovery and delivery phases of your design process. ##### Archive 🗄️ @@ -149,12 +149,12 @@ Check back soon. ![Clear naming of pages makes the right designs easy to find. ](../../../../images/working-with-figma/PageNaming.png) -Inside your files, you will have various kinds of pages. +Inside your files, you have various kinds of pages. Give them each a clear name to indicate their type. #### **Cover** -**Each file should include a cover page.** +**Each file should include a cover page.** This special kind of page presents a clear overview of the file's contents and informs about the owner of the file. Using covers also makes project's overview less cluttered. @@ -201,7 +201,7 @@ such as when the design is ready but the copy still needs review. #### Handoff When you have a version ready for development, -**mark it clearly to show what's ready for handoff** (such as in its name "NPS v1.6 -- Handoff"). +**mark it clearly to show what's ready for handoff** (such as in its name "NPS v1.6---Handoff"). Use this page when [handing off designs for development](/kiwi-use/guides/working-with-figma/handoff/#sending-designs-to-development). ##### **Who benefits from the handoff page?** @@ -213,7 +213,7 @@ Use this page when [handing off designs for development](/kiwi-use/guides/workin #### Remove old iterations -While it is possible to have multiple iterations and multiple files, +While it's possible to have multiple iterations and multiple files, we recommend removing any iterations before the latest 2 or 3 iterations from the file by deleting their pages. Files with many pages can slow down people's work @@ -237,7 +237,7 @@ but the initial file load isn't slowed down by lots of previous work. This page contains all reusable components that are only for this file. This helps to keep all components together in one place -nd also prevents them from getting lost when [older iterations are deleted](#remove-old-iterations). +and also prevents them from getting lost when [older iterations are deleted](#remove-old-iterations). ### Groups @@ -266,9 +266,9 @@ This makes it easy to connect screens into a clear flow with a single hotkey. ### **Screens** -Each screen will be related to others in its group. +Each screen is related to others in its group. If you have some screens that you know will be part of your flow but aren't ready yet, you can include them with [Empty](https://www.figma.com/file/Mutou0a3WLf4bZrApWVRU9Kz/Helpers?node-id=73494%3A34) or [Missing](https://www.figma.com/file/Mutou0a3WLf4bZrApWVRU9Kz/Helpers?node-id=73748%3A6) screen components from the Helpers library, which is automatically included in each team. -This will clearly show what your plans are for the future. +This clearly shows what your plans are for the future. diff --git a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/03-design-flow.mdx b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/03-design-flow.mdx index cb679851cd..aead51aa04 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/03-design-flow.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/03-design-flow.mdx @@ -15,7 +15,7 @@ but in a separate [group](/kiwi-use/guides/working-with-figma/structure/#groups) Once the designs are ready for smaller screens, they can be scaled up to fit larger screens on the desktop. -These will be placed in a separate team ([read about why](/kiwi-use/guides/working-with-figma/#why-are-mobile-and-desktop-split-into-two-teams)) +These are placed in a separate team ([read about why](/kiwi-use/guides/working-with-figma/#why-are-mobile-and-desktop-split-into-two-teams)) and the [designs can be linked](/kiwi-use/guides/working-with-figma/#linking-designs) for easy navigation among them. @@ -39,7 +39,7 @@ Generally, buttons are 44 pts high in iOS and 48 pts in Android. So in Figma, instead of having buttons overly optimized for one platform or the other, button components in Figma are 46 pts high. -This isn't a value that will actually be used, +This isn't a value that is actually be used, but it allows designers to make their designs basically fit with each platform. The recommendation to follow a [4-pixel grid system](/foundation/spacing/) for designs still holds, diff --git a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/04-collaboration.mdx b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/04-collaboration.mdx index 7e491e9548..71d7a6b1e6 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/04-collaboration.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/04-collaboration.mdx @@ -20,11 +20,11 @@ To make sure the right people see a specific design: 1. Click **Share** in the top right. 2. Enter a person's name to find them within the organization or email to invite external reviewers. -3. Unless you are inviting another designer/writer, +3. Unless you're inviting another designer/writer, leave the permissions as **can view** (which includes the ability to comment). - Every person with editing permissions costs money, - so please don't give editing permissions unless it is necessary. + so please don't give editing permissions unless it's necessary. 4. Send an invitation to notify them by email. 5. Repeat for everyone you want to invite. @@ -42,9 +42,9 @@ and let you @ others in the team to notify them directly. To get started commenting, press the C key or click the **Add/Show Comments** button (a speech bubble) in the top left. -A list of comments will appear on the right, with the most recent at the top. +A list of comments appears on the right, with the most recent at the top. If you've visited the file before and have unread comments, -the **Add/Show Comments** button and the comments in the list will be highlighted with a red icon. +the **Add/Show Comments** button and the comments in the list are highlighted with a red icon. To add new comments, click next to what your comment relates to and add your message. @@ -61,7 +61,7 @@ Note that you can set different statuses for the design and the copy. If you want to get specific people involved in the review, [add a comment](#commenting-on-designs) and tag them in it. -This will ensure they get a notification that there's something for them to see. +This ensures they get a notification that there's something for them to see. When all comments have been resolved, you can change the status to Ready for development diff --git a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/05-handoff.mdx b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/05-handoff.mdx index 758946796a..80ec8432d7 100644 --- a/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/05-handoff.mdx +++ b/docs/src/documentation/06-kiwi-use/03-guides/03-working-with-figma/05-handoff.mdx @@ -22,19 +22,19 @@ such as by sharing the next section of this page with them. ## **👨‍💻** **Developing based on designs** The first thing to remember is that the designs you're looking at might not be finalized yet. -Designers will share works in progress with you because they value your feedback in shaping the design. +Designers share works in progress with you because they value your feedback in shaping the design. So pay attention to the structure of the designs to see where they are in the process. See especially [how handoff pages are structured](/kiwi-use/guides/working-with-figma/structure/#handoff). If you're looking to see the specific parameters of the design, -you'll find them in the **Code** tab on the right +find them in the **Code** tab on the right (automatically selected if you only have view/comment permissions). The code can be displayed for CSS, iOS, and Android. These can be used as guidelines when developing your own implementations. -If you select components, their names and descriptions will show as code comments. -Similarly, the names of selected styles will appear as comments, +If you select components, their names and descriptions appear as code comments. +Similarly, the names of selected styles appear as comments, which can help you determine which [design tokens](/foundation/design-tokens/) to use. ![GATSBY_EMPTY_ALT](../../../../images/working-with-figma/FigmaCodeComments.png) @@ -51,7 +51,7 @@ Code tab after clicking the **+** next to **Export**. By default, everyone who can view a file can copy text from it. To select text, select the given layer that contains the text -(dragging your cursor won't work). +(dragging your cursor doesn't work). Then you can copy text as normal (⌘+C, Ctrl+C). You can also open the context menu and select **Copy/Paste** → **Copy as Text**.