Dealing with css conflicts

[Dhaulagiri]

The addon I am writing docs for uses a design system that is based on Tachyons. This is causing me problems in a few cases, most notably with the absolute class added to the nav here. The problem is that because I'm importing my css first before the css from this addon my absolute is superseding positioning applied to the nav by the lg:relative class and therefore always positioning the nav absolutely.

I think there might be a way to fix this particular case, but more broadly do you have any advice on how to address this kind of issue?

[samselikoff]

Yes - we should probably prefix the Tailwind classes we're using, perhaps with ad- so they don't conflict.

I also want to get PurgeCSS in here so we don't ship a bunch of unused classes.

[sglanzer]

+1 on this - I'm also using a modified Tachyons system and I've been overriding templates to "fix" the class conflicts

[MelSumner]

Looks like some stuff is styled on the html elements which can also cause issues: Another example:

[olivier-w]

It looks like tailwind also adds a border-color to every single element.

Is it possible to completely exclude tailwind from ember-cli-docs?

*, *::before, *::after {
    border-width: 0;
    border-style: solid;
    border-color: #dae1e7;
}

[pzuraq]

We do want to provide a consistent theme that addons can use conventionally. The long term goal is to create a unified ecosystem of documentation, so Ember devs can browse docs quickly and effectively (possibly through a single unified website).

If Tailwind has too much overlap with user’s styles, that is tricky, but we can try to change it. I think giving options to disable them encourages users to write their own styles instead, which is counter to that long term goal.

[samselikoff]

@olivier-w this one is from normalize.css which we can definitely add an option to exclude. Curious in this case what problem you're running into with this rule? Is it because you're adding a border-width but then having to change the color?

[olivier-w]

Yeah, adding a border-width adds that color.

But it isn't included in the default normalize.css. It was added in tailwind.

[samselikoff]

We now prefix tailwind classes with docs- so I'm going to close this for now.

@olivier-w please add a comment here if you're still running into trouble, but I don't know how we could completely exclude Tailwind since it's what we use to style our components. Ideally we could "normalize" just our components, and CSS's global nature makes it difficult to use standard tools like normalize.css in an isolated way, but before we tackle that I'd want to understand how you'd want to use Addon Docs without the styling.

[olivier-w]

Thanks @samselikoff. It’s not that I don’t want the styling, it’s that the Tailwind CSS was changing our examples. Finding and overwriting those global selectors was not fun.

We’ve recently decided to move towards React so we probably will not run into this specific issue again.

[samselikoff]

Gotcha, makes sense.

Sad to see you go! If you find yourself using it again, let us know if you run into issues again.

[fschade]

Same thing here, ember-cli-addon-docs is fantastic! But hard to implement if you have an whole ui framework.

Docs are overwriting our docs or our css overwrites Addon docs css. We use bootstrap and that deals a lot with resets. In my opinion the best solution would be if there’s a way to render the demos in a iFrame like way. But this is hard to obtain :(

Are there any tips what we can do?

My first idea was to extend AddonDocs components and add our own css around it. But I cannot find a way to exclude css from docs. It also feels like a hack.

In my opinion the perfect goal is to get AddonDocs agnostic from Addon app and find a way (as said earlier) to differentiate the docs Dom from the demo Dom.

[michaeldrotar]

Not sure if I should open a new issue or maybe it's a tailwind issue, but this was top result on google so might be helpful for others.

Our specific issue is that we're wrapping material components in Ember and using Addon Docs for our styleguide... when creating a textarea component, material has styling like:

.leading,
.trailing,
.notch {
  border-width: 2px
}

Material's other styles ensure that leading has top, left, and bottom borders, trailing has top, right, and bottom, and notch has just top and bottom... but tailwind says:

*,
*::before,
*::after {
  border-style: solid;
}

So now everything has a border and the display breaks.

To @samselikoff's comment above about how to apply Tailwind to just the docs, I would suggest something like this:

/* Revert Tailwind's global styles */
*,
*::before,
*::after {
  border-color: initial;
  border-style: initial;
  border-width: initial;
}

/* Allow docs-* classes to use tailwind global styles */
[class^='docs-'],
[class*=' docs-'] {
  border-color: #dae1e7;
  border-style: solid;
  border-width: 0;
}

Where I'm stuck at is that if I add this to my dummy/app/styles/app.scss file, it's coming after tailwind is injected so it's taking precedence over styles likes .docs-border-r { border-right-width: 1px; } -- I don't think I have a way to add this after tailwind's global and before their utility classes so I'd have to re-define all the tailwind utility classes that are affected for this to work.

Anyone else have ideas on this?

[samselikoff]

I don't have time to work on this now, but for anyone who's motivated here's what needs to happen:

We need to re-work AddonDocs' usage of Tailwind to not include Tailwind's Preflight styles.

These base styles make sites easier & more consistent to work with, but it is possible to use Tailwind's utilities without them. I believe Adam said the biggest change is that the use of border now needs to be accompanied with a border color and border style. You can read some about that here, as well as other changes Preflight brings along – but note that that link is to 1.0, and AddonDocs currently uses Tailwind v0.

Unfortunately right now, AddonDocs uses ember-cli-tailwind which has the preflight directive hardcoded into its modules.css file. So to actually remove preflight, we need to first either (1) add a config option to ember-cli-tailwind, or (2) remove ember-cli-tailwind altogether, and wire up our own postcss pipeline with ember-cli-postcss that includes tailwindcss. This would also allow us to add purgess to the pipeline, which would be ideal. (This very reason is also why I'm going to deprecate the addon and suggest folks set up a postcss pipeline in their own projects.)

Once we exclude Preflight from our Tailwind build, we'll then need to update our components to make sure things look good without the reset. We could either include a new reset like vanilla normalize, or include the option for no reset, so visual addons like Ember Styleguide can bring their own global styles and be guaranteed of no collisions with styles provided by AddonDocs.

The only other alternative I can think right now would be to expose an option that doesn't include any css from AddonDocs, for addons that want full control over styling. Those addons could still use AddonDocs' components as provider/renderless components, so they have things like the version selector in the header and the navigation index in DocsViewer. Then, those addons could style everything on their own.

I originally wanted to add renderless data-provider components for all the data AddonDocs provided, and then rebuild the UI components with those, so others could opt-out of the visual styles AddonDocs provides and still use the data providers. But I never got around to it.

If anyone wants to take this on and needs any help or direction, I am more than happy to provide some guidance!

https://github.com/embermap/ember-cli-tailwind/blob/master/lib/modules.css

[michaeldrotar]

Thanks for the explanation! I could try to take a stab at this if nobody beats me to it (my next few weeks are looking busy).. decoupling styles from data sounds like a future effort... excluding preflight and providing addon docs its own reset sounds pretty trivial, I just need to brush up more on ember's asset pipeline and how addon docs is consuming tailwind and probably a few other things.

Possible option at that point would even be to have a postcss plugin that replaces * with [class^='docs-'],[class*=' docs-'] in addon doc's css files and then maintain preflight's styles for easier upgrades.

Maybe something like this https://github.com/itaoyuta/postcss-selector-replace Though I'd prefer a full selector match or a regex match to the substring match this is doing

Then a postcss rule to use it only for addon doc's own css.

Also feels like this could be a tailwind feature itself.. seeing that they have the prefix config to namespace their stuff, I'd think the prefix should apply to those too... or else true reset styles need to be separated from any styles like the border properties that are just there to make utilities simpler.

[Gorzas]

I'm having a similar problem using the library Materialize but in the other way: the library is changing the base components of ember-cli-addon-docs. I think that it may be possible to have both options: one with Tailwind not changing your own components and also the option to use ember-cli-addon-docs with your own styles. What do you think?

[samselikoff]

Yep, I think a "renderless component" approach would work best here for folks who want to opt-out of AddonDocs' styles.

[michaeldrotar]

Looks like I won't be able to get to this anytime soon after-all... and I'm not sure it's even needed anymore.

The only conflict I came across was the border issue I explained earlier and explicitly adding border-left: none; border-right: none; for the one affected case was a much simpler and more intuitive fix than getting into tailwind guts. I think those styles should've been there regardless and Material made a poor choice by excluding them here.

I'd be curious what other conflicts people are having.. even if tailwind preflight respected the namespace and ember addon explicitly added a css class to every single element it needed to style to avoid any conflicts, there are still cases where things could fail:

• most things need to touch the body element to remove paddings, set min heights, or flexbox it
• many styles, like line-height, are inherited and it'd be unrealistic for a user to explicitly set them on everything to avoid the inheritance
• even if we don't allow tailwind or ember addon docs to use global selectors or tag selectors, user's will invariably want to leverage them so things would still conflict

I think this is just a small price for the savings of using tailwind and ember addon docs.. only way to avoid it I see would be to create your own doc files using just your own css -- which would be great, but also would be alot of work on things that probably aren't important to your actual product.

[psbanka]

I took an initial shot at this by starting with a tailwinds-1 upgrade PR. Hopefully that will get us started on the path to being able to allow an addon to specify that preflight styles should be skipped if they need that (which our addon does).