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 0f144052b8..2cdaeb866e 100644 --- a/docs/src/documentation/01-getting-started/02-for-developers.mdx +++ b/docs/src/documentation/01-getting-started/02-for-developers.mdx @@ -26,8 +26,6 @@ npm install @kiwicom/orbit-components yarn add @kiwicom/orbit-components ``` -Don't forget to also install [styled-components](https://github.com/styled-components/styled-components/) `^4.0.0`. - ## Usage 1. Import the fonts that are used in `orbit-components`: @@ -64,15 +62,6 @@ You can also try `orbit-components` live on [CodeSandbox](https://codesandbox.io ## Typescript Orbit comes with Typescript definition files. -If you're working with Typescript, you need to add a type for `styled-components`. - -```shell -// with npm -npm install @types/styled-components --save-dev - -// with yarn -yarn add @types/styled-components -D -``` ## Main Sections diff --git a/docs/src/documentation/02-foundation/04-color/03-theming.mdx b/docs/src/documentation/02-foundation/04-color/03-theming.mdx index 0dc6d86e06..20a350ac33 100644 --- a/docs/src/documentation/02-foundation/04-color/03-theming.mdx +++ b/docs/src/documentation/02-foundation/04-color/03-theming.mdx @@ -7,34 +7,3 @@ title: Theming You can create your own [design tokens](/foundation/design-tokens/) for themes and use them in your components. - -### Styled components - -For custom usage in `styled-components`, -you should always depend on the actual `theme` property stored inside your context: - -```jsx -import React from "react"; -import styled from "styled-components"; - -const StyledDiv = styled.div` - margin: ${({ theme }) => theme.orbit.spaceLarge}; -`; -``` - -If you don't use a theming context in your application and you still want to use context, -declare `defaultProps` for your styled component: - -```jsx -import React from "react"; -import styled from "styled-components"; -import defaultTheme from "@kiwicom/orbit-components/lib/defaultTheme"; - -const StyledDiv = styled.div` - margin: ${({ theme }) => theme.orbit.spaceLarge}; -`; - -StyledDiv.defaultProps = { - theme: defaultTheme, -}; -``` diff --git a/docs/src/documentation/05-development/01-guides/04-eslint-plugin.mdx b/docs/src/documentation/05-development/01-guides/03-eslint-plugin.mdx similarity index 100% rename from docs/src/documentation/05-development/01-guides/04-eslint-plugin.mdx rename to docs/src/documentation/05-development/01-guides/03-eslint-plugin.mdx diff --git a/docs/src/documentation/05-development/01-guides/03-no-exporting-components.mdx b/docs/src/documentation/05-development/01-guides/03-no-exporting-components.mdx deleted file mode 100644 index fa641158f6..0000000000 --- a/docs/src/documentation/05-development/01-guides/03-no-exporting-components.mdx +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Why we don't export styled components -description: The reasoning and drawbacks behind our decision not to make Orbit components easily extensible. -redirect_from: - - /guides/why-we-dont-want-to-allow-extending-orbit-react-components/ ---- - -We know that Orbit React components are built upon styled-components, -which allow you to easily extend other existing React components with the styled factory. -Still, we, as Orbit maintainers, don't want to allow it, -even though it would allow many of our developers to develop features easily -with a better developer experience. - -Both approaches, allowing such extension and not, -have a lot of pros and cons that have to be considered. -So we would like to clearly state all of them we can and explain our decision clearly. - -## Pros - -We think the following pros to allowing the extension of Orbit React components are the most important. - -### Simpler JSX structure - -Given the nature of how styled-components work, -the main benefit would be a simpler JSX structure. -Mainly because of the possibility of extending our components, -developers could attach additional styles in a very easy way. That would mean fewer wrappers with custom overrides. - -### Better developer experience with Orbit - -We also believe that allowing extension would lead to -a better developer experience when working with Orbit. -Developers would not have to think if our components support a particular use case -and would simply override the behavior or visual style of our components. - -## Cons - -On the other hand, we think that allowing the extension of Orbit React components -would bring us and also our frontend developers many cons -that might not manifest immediately, but most probably would in the future. - -### Consistency issues - -One of our main long-term goals is to ensure consistency across our applications. -We believe that allowing extension would lead to worse consistency -since developers would have a very easy way to implement designs -that might not be aligned with the current possibilities that Orbit provides. -It would lead also to fewer requests for enhancements, new features, and bug fixes -and would slow down the growth of Orbit in some way. - -### Dependent on Orbit DOM structure - -Most of our components may be considered very simple, -or by some definitions atoms or molecules. -But in reality, their DOM and style structure may not be that simple---as a single DOM element. -So it can be hard to properly extend some Orbit React components -without exact CSS selectors that follow the exact DOM structure. -For the future sustainability and maintainability of our components, -we can't provide or support their DOM structures, -which can be changed with refactoring or major visual updates. - -### Would need to document API for all styled-components - -If we exported, we would have to document all of the inner styled-components -that make up Orbit React components and have them publicly documented. -This would add unnecessary complexity on our shoulders -and require us to make updates and releases less often. - -### New versions would require more work - -As said before, having a more public and documented API would mean -that between some minor versions (and major versions once we release the first major) -it would most likely be harder to release quick updates of the newest version to production -and would require a lot of work in users' repositories. - -### Impossibility to lint all overrides and custom styles - -As far as we know, there isn't any tooling that would allow us to control or determine -which CSS properties are being used in the extended component and which are being overridden. -So we couldn't transparently support how our components would be used. -This, in the end, could lead to inconsistent behavior or visual style for our applications, -even though we can't prohibit all possibilities when it comes to custom CSS overrides. - -### Extended functionality requires running more JS code - -Given the nature of how styled-components work, -allowing extension could lead to unnecessary complexity in UI components -and also more time-consuming runtime. -The most problematic part is managing the StyleSheetManager context state, -which can be expensive. -And with combinations of multiple extensions, it could lead to performance issues. - -### You'd become a maintainer of the UI - -Most importantly, allowing extension would mean that you'd be becoming a maintainer of the UI. -We wouldn't be able to provide you with a guarantee over the UI that you need to develop. -You should be responsible only for minor and major layouts that the feature requires -and not for elementary pieces of the UI. -Last but not least, you should spend most of your time on implementing functionality -and not on the UI, which should be consistent in our applications and solved on a systematic level. - -Neutral: - -- Fewer support requests/fewer versions -- Fewer reports that something doesn't work (bug fixes, features requests) -- Solving topics on design level and systematic approach - -## On balance - -Overall, for us, allowing the extension of our components -would bring too many drawbacks without enough benefits. -It would mean we would get fewer requests for support and fewer opportunities -to build Orbit into something better with more features and versions. -It would mean we wouldn't be solving issues systematically -and so you would have to spend more of your time solving minor issues. - -We understand the lack of flexibility is a drawback. -That's why we've started other initiatives to give you more control -while remaining inside the Orbit design system. -For example, we began introducing primitive components, -which give you all of the same basic functionalities with a lot more control over the visual style. - -If there's something that'd you'd like to have control over, let us know, -in [#plz-orbit](https://skypicker.slack.com/archives/CAMS40F7B) -or directly in our [GitHub repository](https://github.com/kiwicom/orbit). -We want to cover all major use cases and work together to make Orbit the best it can be. diff --git a/docs/src/documentation/05-development/03-hooks/usetransition.mdx b/docs/src/documentation/05-development/03-hooks/usetransition.mdx deleted file mode 100644 index 3c4032fe65..0000000000 --- a/docs/src/documentation/05-development/03-hooks/usetransition.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: useTransition -description: Animate adding and removing elements from the DOM ---- - -import UseTransitionReadMe from "@kiwicom/orbit-components/src/hooks/useTransition/README.md"; - -